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Preface 


This hook is intended as a compact reference guide to the Atari ST range of 
computers, it provides detailed information on the Atari ST hardware, an overview 
of the operating systems and the operating system calls. 

The majority of the book has been prepared in both decimal and hexadecimal 
notation to make reading and data entry less complicated for the beginner, and those 
who wish to use the VDI and AES tables from BASIC. I hope the use of decimal 
will not be too distressful to the purists, but most assemblers will accept either 
format as an input. The diagramatic presentation of data in memory and of stacks 
follows the Motorola MC68000 user’s manual format of low memory towards the 
top of the page; presentation of memory maps follows the convention of high 
memory towards the top of the page. All memory representations are annotated to 
avoid confusion. 

The Atari ST range of computers contain the largest ROM (192K) of all the current 
home/low cost business computers available. This offers an enormous wealth of data 
and routines that the user may wish to access; about six times that of most other 
computers, this information is presented in a condensed group tabular form to 
provide association. General descriptions of all the facilities available (disk, file, 
interfaces etc) are provided to present the reader with at least an outline understand- 
ing of their operation. 

The book covers the programming of an Atari ST 16-bit computer in three parts: 

Chapter 1 gives an overview of the Atari ST hardware and expansion ports, also 
included is a short description of the peripheral interface circuits. 

Chapter 2 presents an overview of the operating systems, the management of 
memory and resources, control of serial I/O, screen functions and file handling. 

Chapter 3 provides the operating system calls for both GEM and TO S, the A-line 
graphic functions and the intelligent keyboard command instructions. 

Appendices contain the system variables, configuration registers and a summary of 
the MC68000 instruction set. 
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Foreword 
by Jack Tramiel 

When we introduced the ST series of computers at Atari, we coined the phrase 
Tower without the Price'. This sums up all that had been in our minds when we 
decided to design a range of powerful but low-cost machines that could be used for 
all applications ranging from sophisticated games to complex business and scientific 
uses. 

During the past few years, ever since I was responsible for bringing the first mass- 
produced electronic calculators and then the first true computers to the public at an 
affordable price, my whole aim has been to bring the benefits of technology to those 
of average income. We have to get high technology out of the hands of the few into 
the hands of the many. As I have said before we want ‘classes for the masses 1 . If you 
give somebody some sophisticated machinery then you’ll be surprised what they can 
do with it. Time and again we have been amazed at what users have done with the 
technology when it is made freely available at an affordable price. 

And that brings me on to this series of books, edited by my old acquaintance Robin 
Bradbeer, It is impossible to give all the information necessary to completely cover 
all the uses of a computer in the instruction manual. Also, if more than one person 
explains something they bring out differing strengths of the system. This series of 
books should help all users of the ST to get to know the machine better and 
therefore use it more productively. Who knows, we at Atari may yet again be 
surprised by what you, the user, can do with the affordable technology that we have 
provided. 

Jack Tramiel 
1986 
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Chapter 1 
Atari ST hardware 
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ATARI ST BLOCK DIAGRAM 



Floppy Disk 


Parallel 
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General hardware description 

The Atari ST computer system consists of a console unit featuring an integral 
keyboard, a display screen, sound subsystem, peripheral input/output and an 
operating system. Expansion ports are provided for the connection of a variety of 
peripheral devices i.e. a mouse, joystick, printer, modem, floppy disk, ROM 
cartridge application program etc. 

The Atari ST console contains an 8MHz MC68000 16 bit microprocessor, at least 
512K of resident RAM and a 192R ROM operating system. A Mostek MK68901 
multi function peripheral (MFP) device provides the general purpose interrupt 
control and timers and a single direct main memory access channel, giving both high 
and low speed access support, through a 32-bit FIFO to the 8 bit device controllers. 

User input is via the integral intelligent keyboard, an external mechanical and or 
optical mouse, or a switch type joystick. The keyboard communicates bidirectionally 
at 7 Kbits /s with the main unit via a 1MHz HD6301 8-bit microprocessor in the 
keyboard unit, and a MC6850 asynchronous communications interface adapter 
(ACIA) in the ST console. 

The display may be either a monitor, high resolution black and white or colour (The 
Atari STM also caters for a standard television display unit). The console 
interrogates the display device to determine the type attatched, ensuring the high 
frequency sync signals are not sent to low frequency monitors. There are three 
display resolutions, 320 x 200 16 colour low resolution, 640 x 200 4 colour medium 
resolution and 640 x 400 high resolution monochrome. The display memory is part 
of the main memory and provides a matching bit-pixel relationship to the physical 
screen in high resolution mode, with the screen origin at 0,0 in the top left hand 
corner being bit 15 of word 0. The monochrome monitor (SMI 24) is capable of a 
high quality display of the high resolution 640 x 400 ST graphics. 

The music system sound effects and audio feedback output arc created through the 
monitor or television speaker, at frequencies in the range of 30Hz to 128Khz, via 
three independant voice channels. The programmable sound generator outputs may 
consist of a noise and a tone mixed at a fixed or variable amplitude defined by the 
envelope generator. 

The musical instruments digital interface (MIDI) enables the ST to integrate with 
music synthesisers, sequencers, drum boxes etc. which incorporate the MIDI 
interface; enabling OMNI, POLY and MONO networking. 

Printer output is achieved via the parallel and RS232 interfaces, the latter also being 
available for modem and general communication. 

The floppy and hard disk interfaces provide the off-line data and program mass 
storage facilities. The hard disk drive interface is accessed through the DMA 
controller but the hard disk controller itself is off board. An on-board Western 
Digital WD1772A supplies the floppy disk drive controller which interfaces the 
Atari ST 3.5'’ disk drives (SF354 or SF314). 
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MONITOR 

RGB composite 


DMA PORT 

Direct 
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access 

10 Mbyte 
Hard disk 
interface 


PARALLEL 

PRINTER 

INTERFACE 

Centronics 

8 bit port 
bi-directional 

MC 68901 


MIDI I/F 

Omni-Poly 

and 

Mono 

network 

MC 6850 

in put /output 


PLUG-IN CARTRIDGE 

Applications 

languages 

128K ROM max 


FLOPPY DISK 

349 Kbytes 
formatted 


MAIN SYSTEM 

8 MHz 68000 processor 
16 Mbyte addressing range 

Graphics subsystem 

32k bit map 
320 x 200 16 colours 
640 x 200 4 colours 
640 x 400 monochrome 

Sound subsystem 

Programmable sound 
generator (PSG) YM 2149 

3 independant voices 

ROM192K 
RAM >= 512K 


Packages 
GEM 
Desktop 
Applications 

MC 6850 


FLOPPY DISK 
INTERFACE 

Supports 
two drives 

WD 1772 A 


RS232 I/F 
m/dtr/cts/dcd/ring 
50-19200 baud 
MC 68901 



MOUSE/JOSTICK 
PORT 

Two-button 
mouse 


INTELLIGENT KEYBOARD 
HD 6301 


JOYSTICK PORT 
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The operating system may be either in 192K of ROM, or an image file on disk 
loaded by the disks boot sector, featuring the GEM operating environment of 
windows, icons* pull down menus. The ST is also supplied with two language 
implementations* an interpreted BASIC and Atari LOGO. 

The ST can accept other operating systems loaded via the boot sector or brought up 
by a driver in an * AUTO* folder. 


Main system surrounded by device subsystems 
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Atari ST console expansion 


Power 

7 way DIN 7P plug 
(if external) 


Midi out 

5 way DIN 5S socket 


Midi in 

5 way DIN 5S socket 



Video 

RCA pin jack (if fitted) 



Monitor output 
Composite Si RGB 

13 way DIN 13S socket 



Parallel 8-bit bidirectional 
printer port 

25 way DB 25S socket 


50000000000000 
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connections overview 


[oooooooooooooo] 
0000000000000 / 


RS232C Modem port 

25 way DB 25P plug 


Floppy Disk Controller 

(Up to 2 drives)' 

14 way DIN 14S socket 




Hard disk port (DMA) 

19 way DB 19S socket 


ROM expansion port 

40 way socket 
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MONITOR / TV OUTPUT 


Monochrome Monitor 

Atari SM124 
7 1 .25 Hz scan rate 

Colour Monitor 

Atari SC 1 224 RGB 
50/60 Hz scan rate 


Television ('where fitted) 

RCA pin jack 

Core: RF modulated video 

Shield: Ground 



13 way DIN 13S socket 

Sync 5V active low 3.3 Kohm 
Audio IV pk-pk 10 Kohm 
Video IV pk-pk 75 ohm 


Pin Function ST signal processing device 


1 Audio out 

2 Composite video 

3 General purpose output TTL PSGl/OA 

4 Monochrome detect T FL MFP 

active low* IK pull up to 5V 

5 Audio in 

6 Green 

7 Red 

8 Ground 

9 Horizontal sync 

10 Blue 

1 1 Monochrome 

12 Vertical sync 

13 Ground 
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MONITOR OUTPUT 

The monitor output supports either a high resolution black and white monitor 
(Atari SMI 24) or a medium resolution colour monitor (Atari SC 1224). Sound is 
reproduced through the display device speaker. 

Any suitable monitor may be attached^ typical performance: 



Low 

Resolution 

Medium 

Resolution 

High 

Resolution 

Resolution 

452 x 585 pixels 

653 x 585 pixels 

895 x 585 pixels 

Video Bandwidth 

lOMhz 

ISMhz 

ISMhz 

Slot pitch (typ) 

0.64mm 

0.41mm 

0.31mm 

Vertical scan 

50/60 Hz 

50/60 Hz 

7L2Hz 

Input video 

I VDC pk-pk 



audio 

1VDC pk-pk 



Sync 

5 VDC active low 

_J 



®J : 


I 1 
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PARALLEL PRINTER INTERFACE 






MFP 


O 

PSG I/O port B 


O 

I/O port A 5 


0 


I Strobe 

2-9 Data 

II Busy 


Main console 


I jO port 


The parallel port interface provides an 8 -bit data communication channel controlled 
by a strobe signal generated by the ST, indicating that data bits are available on the 
data lines for transfer to the peripheral, and a busy signal generated by the 
peripheral (usually a printer) indicating either that it is busy, has a fault or possibly 
out of paper if a printer. 


25 way DB 25 S socket 


13 


14 


25 


Pin 

Function 


1 

Strobe 


2 

Data 1 


3 

Data 2 


4 

Data 3 


5 

Data 4 

Data generated at a typical 

6 

Data 5 

rate of 4fcbytes/s by the 

7 

Data 6 

PSG I/O port B 

8 

Data 7 


9 

Data 8 


10 

n.c 

Acknowledge is not supported 

11 

Busy 


12-17 

n*c 


18-25 

Ground 



The parallel port strobe signal generated by the PSG I/O port A (pin 1), supplies the 
data transfer synchronization. 

The busy signal (pin 11) is read by the console MFP and provides the handshake 
contra L 

The strobe signal is active low, the busy signal active high, with a IKohm pull up 
resistor to + 5V. All signals are at TT L levels. 
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RS232 MODEM INTERFACE 




0 


<r~ 

O 

MFP 

4- 

o 


4- 

° 


4— 

o 




PSG write only 



I/O port A 3 


o 

bit no. 4 


o 

(FF8802) 




Main console //O port 


2 

Tx 

transmit 

3 

Rx 

receive 

5 

CTS 

clear to send 

8 

DCD 

data carrier detect 

22 

RI 

ring indicator 

4 

RTS 

ready to send 

20 

DTR 

data terminal ready 


The RS232 interface is controlled via the PSG I/O port A (RTS and DTR) and the 
MFP (CTS, DCD and RI) transmitting and receiving data within the range 50 to 
192K baud, the timing synchronization is generated by the multi -function processor 
(MFP) timer D. 


The interface supports hardware handshake control: 


Transmit PSG I IO port A 
RTS 
DTR 

25 way DB 25 P plug 



Receive MFP inputs Software 

CTS Ring control is through 

DCD Xon/off protocol. 


Pin 

Function 


1 

Grd 

Protective ground 

2 

Tx 

Transmit data 

3 

Rx 

Receive data 

4 

RTS 

Ready to send 

5 

CTS 

Clear to send 

6 

n/c 


7 

Gnd 

Signal ground 

8 

DCD 

Data carrier detect 

9-19 

n/c 


20 

DTR 

Data terminal ready 

21 

n/c 


22 

Ri 

Ring indicator 

23-25 

n/c 



RS232 signal levels 

Zero + 3v to + I2v 

One -3vto-12v 
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FLOPPY DISK INTERFACE 



4 
8 

9 

10 
12 
2 

5 

6 


index pulse 
motor on 
direction in 
step 

write gate 
select side 
drive 0 
drive l 


The floppy disk interface is based on an on-board Western Digital WD 177 2 A disk 
controller and supports a maximum of two drives. There is no hardware sensing of 
disk removal. The drives provide fast storage and retrieval of data and programs on 
3.5” flexible micro disks. 

14 way DIN I4S socket 



Pin 

Function 


1 

read data 

TTL active low, IK pull up 

2 

select side 0 

TTL active high (high system reset) 

3 

logic ground 

pair with read data 

4 

index pulse 

TTL active low, IK pull up 

5 

select drive 0 

TTL active low (high system reset) 

6 

select drive 1 

TTL active low (high system reset) 

7 

logic ground 

pair with write data 

8 

motor on 

TTL active low 

9 

direction in 

TTL active low 

10 

step 

TTL active low (inverted) 

11 

write data 

TTL active low 

12 

write gate 

TTL active low 

13 

track 00 

TTL active low, IK pull up 

14 

write protect 

TTL active low, IK pull up 


The shield must not be connected on the ST side. 


Data is written to 512 byte sectors. 


DIRECT MEMORY ACCESS PORT 


This port can be use to provide access to a hard disk or a compact disk. The hard 
disk controller, not supplied with the basic ST system, communicates through a 
sequence of six bytes which provide format, read and write facilities etc. The 
command protocol used is referred to as ANSI X3T9.2, a SCSI-like small computer 
systems interface, of which the ST supports a small subset. 

The Atari hard disk descriptor block consists of a six byte command packet 
conforming to the following: 


Six byte command packet 


Byte 

Bit 



No. 

No. 

Function 

Range 

0 

0-4 

Operation code 

0-31 


5-7 

Controller number 

0-7 

1 

0-^1 

Head number 

0-31 


5-7 

Drive number 

0-7 

2 

0-5 

Sector number 

0-63 


6“7 

Cylinder number high 


3 

0-7 

Cylinder number low 


4 

0-7 

Sector count 


5 

0-7 

Control byte 



Hard disk command code summary 


Dec 

Op code 

Hex 

Command 


5 

05 

Verily track \ 

Multi-sector 

6 

06 

Format track I 

transfer 

8 

08 

Read sector t 

with implied 

10 

0A 

Write sector 

seek 

11 

0B 

Seek 


13 

0D 

Correction pattern 


26 

1A 

Mode sense 



There is only one DMA channel which is shared by both high- (up to 8 Mbit/s) and 
low- (250 to 500 Kbit/s) speed 8-bit device controllers. 


DMA interface port socket 

1 9 way DB 1 9S socket 
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Pin 

Function 

Signal type 

1 

data 0 v 


2 

data I ; 

1 

3 

data 2 


4 

data 3 | 

Y TTL 

5 

data 4 | 

6 

data 5 


7 

data 6 i 

1 

8 

data 7 / 


9 

chip select 

TTL active low 

10 

interrupt request TTL active low, IK pull up 

11 

ground 


12 

reset 

TTL active low (system reset) 

13 

ground 


14 

acknowledge 

TTL active low 

15 

ground 


16 

A1 

TTL 

17 

ground 


18 

read /write 

TTL 

19 

data request 

TTL active low, IK pull up 
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MUSICAL INSTRUMENT INTERFACE (MIDI) 



Rx receive data 
return 




The MIDI interface functions through an MC6850 asynchronous communications 
interface adaptor (A Cl A) whose control /status register is located at $FFC04 
(16776196); data is passed in the register at offset 2 from the control/status register. 


Data is transmitted serially via the MIDI ports through 2 pins asynchronously using 
the protocol: 


One start bit 
Eight data bits 
One stop bit 
No parity 
31.25 Kbaud. 


The MIDI ports operate in 
RS232 current loop mode, that is: 
Signal levels: 

Zero 5 mA 

One no current 


The MIDI OUT port also supports the optional through port which merely 
provides the MIDI IN signals through an opto-coupled isolator at the MIDI OUT 
connector. 


Control of the port is available through the ST's extended BIOS. 


MIDI in 


MIDI out I thru 


5 way DIN 5 S socket 


5 way DIN 5S socket 


(. 



n 

3 \! 

•*/> 

3 

v*. *y 


r< 


^2 4 

Pin 

Function 

Pin 

Function 

1 

me 

1 

Through t'mit data 

2 

n.c 

2 

Shield ground 

3 

n.c 

3 

Through loop return 

4 

In receive data 

4 

Out transmit data 

5 

In loop return 

5 

Out loop return 


The MIDI ports may be used to network data between connected computers. 
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plug-in cartridge port 

This port provides a plug-in cartridge facility that does not sense in hardware the 
presence of a cartridge. The cartridge ROM occupies addresses in the range. 

$FA0000{ 16384000) to SFBFFFF (16515071)- maximum 128 Kbytes 

40 way 40 S socket 


39 




1 1 1 1 1 1 1 1 1 1 1 i 1 1 1 1 1 1 1 1 1 1 n f 1 1 1 1 1 1 1 1 1 1 1 1 1 1 
ii 1 1 ii ii 1 1 ti «i ii 1 1 tin i mi ii m ii 


iTTTT h 

UlilF 


40 


Pin 

Function 

Pin 

Function 

1 

power + 5 Vdc 

21 

address 8 

2 

pow T er + 5 Vdc 

22 

address 14 

3 

data 14 

23 

address 7 

4 

data 15 

24 

address 9 

5 

data 12 

25 

address 6 

6 

data 13 

26 

address 10 

i 7 

data 10 

27 

address 5 

8 

data 1 1 

28 

address 12 

9 

data 8 

29 

address 1 1 

10 

data 9 

30 

address 4 

11 

data 6 

31 

ROM3 select 

12 

data 7 

32 

address 3 

13 

data 4 

33 

ROM4 select 

14 

data 5 

34 

address 2 

15 

data 2 

35 

upper data strobe 

16 

data 3 

36 

address 1 

17 

data 0 

37 

lower data strobe 

18 

data 1 

38 

ground 

19 

address 13 

39 

ground 

20 

address 15 

40 

ground 


Only the lower 15 address lines are available to the ROM cartridge which does not 
provide a ‘write' line. 
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Intelligent keyboard (ikbd) interface 

The Atari intelligent keyboard performs a variety of functions that include the 
decoding of the key switch matrix, decoding mouse, trackerball and joystick: data 
and providing the time of day. It communicates with the main processor over a high 
speed bi-directional serial link providing a convenient mouse /joy stick interface. 

The keyboard consists of a series of make /break key switches for which the ikbd 
generates keyboard scan codes for each key press and release, chosen mainly for 
compatibility with the Digital Research graphic system (GSX). The key codes (see 
table in appendix D) are defined for the whole range of international keyboards such 
that each code has a predefined key press meaning, irrespective of the presence of 
the key switch. The break code for each key is signified by bit 7 of the corresponding 
make code for the key being set; the codes #$F6 to #$FF are reserved for keyboard 
system functions. 

The keyboard controller contains a 1 MHz HD6301 8-bit microprocessor that 
communicates with the ST's MC6850 asynchronous communications interface 
adaptor (ACIA) at a fixed 7.8 Kbit/s. The keyboard not only transmits the encoded 
key scan codes (with a two key rollover), it also enables the programmer to 
interrogate the status, define the read rates and sensitivity of the mouse and joysticks 
under software control. 

The time- of- day clock incorporated in the keyboard controller is held to a resolution 
of 1 second and may be read and set from software. The keyboard may be reset, 
without affecting the time held by the clock, to its power-up parameters. 

When reset, the keyboard controller performs a simple ROM (checksum), a scries of 
RAM and key (stuck) checks, correct operation is indicated by the return of the 
version/release number of the ikbd controller. 
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Mouse/ joystick interface 

The mouse and joysticks work on the basic unit of an l event\ this is defined as either 
the opening or closing of a switch, or of motion beyond a predefined programmable 
threshold leveh The mouse is capable of a resolution of 200 events per inch (4 
events, 'mm) and is scanned at such a rate as to permit tracking velocities of up to 10 
inches per second (250mm/ s) 3 at a maximum pulse phase error of 50% . 

Motion, which produces make then break cursor keycodes, can be reported in three 
different ways: relative, absolute and cursor key motion (motion per keystroke is 
independently programmable in both axes). The mouse buttons can also be treated 
as part of the mouse or as additional keyboard keys. 


9 way DB 9P plug 


1 2 3 4 5 

Port 0 is configured 

i ***** / 

for mouse operation 


Port 1 is the second 

6 7 8 9 

joystick interface 

Joystick 

Mouse! Joy stick 0 

Pin Function 

Function 

1 Up 

XB/Up 

2 Down 

XA/Down 

3 Left 

Y A /Left 

4 Right 

YB/ Right 

5 reserved 

me 

6 Fire 

left button/Fire 

7 Power 

+ 5v 

8 Gnd 

Ground 

9 n.c 

right button, 'Joystick 1 tire 


The mouse unit provides interactive input to programs like the desktop applications , 
permitting a convenient method of selecting from a menu of facilities shown 
symbolically as icons or simply as text. Port zero is configured for the mouse, but 
may also be connected to a joystick. 

The joystick is invariably used in games applications; but may also be used instead 
of the cursor keys, for fine control of the screen cursor position (one pixel 
movement). 

The joystick fire and mouse buttons close to ground. 
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Power supply 


The power supply provides power for the main system board, the keyboard 
controller, any connected expansion ROM and expansion RAM. 

The supply is fused, the levels are regulated for over-voltage and incorporate over- 
current protection* 


7 way DIN 7 P plug 



Pin 

Function 

l 

+ 5 VDC 

2 

n.c 

3 

Ground 

4 

+ 12 VDC 

5 

“12 VDC 

6 

+ 5 VDC 

7 

Ground 


Power levels: 


15 VDC @ 3A 

5% 

+ 12 VDC @ 0.03 A 

10% 

-1 2 VDC @ 0.03 A 

10% 


The power supply may be integral with the main unit. 
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Processor device outlines 


MC68000 8 MHz microprocessor 
WD1772A floppy disk controller 
MK68901 multi-function processor 
MC6850 asynchronous communications interface adaptor 
YM2149 programmable sound generator 

Custom designed devices (ULAs): 

Direct memory access controller (DMA) 
Memory management unit (MMU) 

Video controller (Shifter) 

General housekeeping (Glue) 
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MOTOROLA MC68000 MICROPROCESSOR 


Signal IfO 

The following is a very brief description of the signal I/O of the Motorola 
MC68000, 



Address bus 


Data bus 

Asynchronous 

control 

Bus 

arbitration 

control 


Interrupt 

control 


I 


A high-density* n-channel, silicon-gate depletion load 16-bit microprocessor in a 64 
pin DIL package. 

The address bus (A0-A23) enables the MC68000 to address 16 megabyte of data or 8 
Megaword of instructions. The address bus provides the level being serviced* 
during an interrupt, on address lines AO to A3 while A4 to A23 are held high. 

The data bus (D0-D15) enables the transfer of word and byte-sized chunks of data. 
During an interrupt acknowlege, a vector number may be placed on lines DO to D7 
by a peripheral device. 

Bus arbitration control allows a peripheral device to control the MC68000 bus (bus 
master); any external request will be granted on a priority basis between the 
competing devices. 

Interrupt control provides a priority level from peripherals requesting processor 
control enabling selection of multiple interrupts on a priority basis. Zero implies 
that there is no interrupt present and 7 is a non maskable interrupt. 
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Level 

Autovector 

7 (high) 

Non maskable interrupt 

6 

MC68901 multi-function processor 

5 

— 

4 

Vertical blanking sync. 

3 

— 

2 

Horizontal blanking sync. 

1 (low) 

— 


Sysrewf control informs the processor that bus errors have occurred and also resets or 
halts the processor. 

Processor status: each time a memory or I/O call is made the processor provides the 
following information on the processor status lines to a peripheral device: whether 
the processor is accessing data or program memory space or servicing an interrupt; 
and whether the processor is in user or supervisor mode. 

The Motorola MC680QG*s separate parallel address and data buses are used to 
transfer data using an asynchronous bus structure controlled by the processor* 
internal or external, which has current bus control. 

Interfacing with the 8 -bit M6800 and 6500 family of synchronous peripheral devices 
is catered for through the use of memory -mapped I/O and a modified bus cycle. 
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WD1772A FLOPPY DISK CONTROLLER 


$FF8604 

access 

data 

byte 

$FF8606 

mode 

control 



The WD1772A floppy disk controller supports eleven instructions, these should 
only be loaded into the data byte register when the status bit (bit 5, 3FFFA01) is 
off. The instructions enable head location, reading and writing sectors, tracks and 
the forced interrupt of a disk operation: 


Instruction byte ($FFS 604 ) 


Restore 

Seek 

#300 

#810 

Seek rate ( ms) 
+ #$00 2 


Step 
Step in 
Step out 

#$20 Update track 
#$40 register 
#$60 + #$LQ 

+ #801 3 Verify 
+ #802 5 +#84 

+ #803 6 

Spin- up 
disable 
+ #$08 

Read sector 
Write sector * 

#380 Multiple sec 
#8 AO +#310 



Read address 
Read track 
Write track * 

#30) Add 30 ms delay 

#8E0+#804 

#8F0 



Force interrupt 

#$D 0 + #$00 End wi th no i n ter ru pt 

+ #$04 Interrupt on index pulse 
+ #$08 Immediate interrupt 



* May contain + #$02: Write precompensation disabled. 

Write sector may also contain + #$01 : Write deleted data mark. 
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Commands are passed to the FDC (and an external HDC), by selecting the 
appropriate FDC or HDC function (Read status/write commandj sector, track or 
data) through the configuration register (8FF8606) and sending instructions or data 
via the access byte (SFF8604). 

Select FDC/HDC function (SFF 8606 ) 


Write FDC DMA #80 Read status /Write command 

#8100 #880 #|10 #81 Track 


Read HDC 1772 #82 Sector 

#800 #$00 #800 #83 Data 
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MC68901 MULTI-FUNCTION PROCESSOR 




The MC68901 contains a single channel US ART capable of operating in full 
duplex, at a rate of 62,5Kb/s asynchronous, IMb/s synchronous from an internal or 
external Baud rate generator. The US ART also supports DMA handshake signals 
and modem control. 


There are four timers with independant operation and vectored interrupts, the 
timers have the following preferred timer uses; 


Timer A: 
Timer B: 
Timer C: 

Timer D: 


Stand alone applications and independent software vendor. 

Primarily Screen Graphics (hblank, sync etc.) 

System timing (GSX, GEM, Desktop, etc). Suitable for delays and 
general timing applications (200 Hz). 

RS 232 port baud rate control. 


S 3 


Eight individually programmable I/O pins with interrupt capabilities are also 
available. 
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MC68901 interrupt control 

MFP hardware bound interrupts 


Priority Function 


15 high 
14 
13 
12 


11 

10 

9 

8 


7 

6 

5 

4 


3 

2 

1 

0 low 


* Test MC6850 status bit to differentiate between keyboard 

and MIDI interrupts. 

MFP configuration registers located at address $FFFA01 (16775681) 


Offset 

Dec 

r Function 

Hex 

Offset 

Dee 

Function 

Hex 

I 

01 

General purpose I/O 

25 

19 

Timer A control 

3 

03 

Active edge 

27 

IB 

Timer B control 

5 

05 

Data direction 

29 

ID 

Timers C & D control 

7 

07 

Interrupt enable A 

31 

IF 

Timer A data 

9 

09 

Interrupt enable B 

33 

21 

Timer B data 

11 

0B 

Interrupt pending A 

35 

23 

Timer C data 

13 

0D 

Interrupt pending B 

37 

25 

Timer D data 

15 

OF 

Interrupt in-service A 

39 

27 

Sync character 

17 

11 

interrupt in-service B 

41 

29 

Usart control 

19 

13 

Interrupt mask A 

43 

2B 

Receiver status 

21 

15 

Interrupt mask B 

45 

2D 

Transmitter status 

23 

17 

Vector base address 

47 

2F 

Usart data 


Monochrome monitor detect GPI (7) 

RS232 ring indicator GPI (6) 

Timer A Timer A 

RS232 receive buffer full 


RS232 receive error 
RS232 transmit buffer empty 
RS232 transmit error 
Horizontal blanking counter 


Timer B 




Disk drive controller GPI (5) 

Keyboard and MIDI * GPI (4) . 

T imer C (sy stem dock ) T i mer C 

RS232 baud rata generator Timer D 


GPU operation done 
RS232 dear to send 
RS232 data carrier detect 
Parallel port busy 


GPI (3) 
GPI (2) 
GPI (1) 
GPI (0) 




The MC68901 usart registers are accessible from Extended BIOS. 


SYNCHRONOUS CHARACTER REGISTER 



3 

3 

nn 

3 

33 

3 

Ll. 


Used 10 synchronize incoming received data acting as the matching character 


(scr - $FFFA27) 


USART CONTROL REGISTER 


7 6 5 4 3 2 10 


CLK 


0 

0 

1 

I 

0 - normal 

1 - Div 16 


0 - od d 

1 - even 

0-off 
1 - enable 


1 

I - async Start -4 2 

1 

0 - async and -4 Vi (used by div 16) 

0 

1 - async stop -4 1 

0 

0 - sync bits ->0 0 

8 bits per word 


7 bits per word 


6 bits per word 


5 bits per word 



(ucr = $FFFA29) 


TRANSMIT STATUS REGISTER 

i n ■ i' 5 i~ r r~ r T 


BE 


UE 


AT 


END 


33 


(tsr - $FFFA2D) 


TE 


0 - disable Tx and dear flag 

1 - enable normal operation 

0 - high imp Configu re Tx 

1 - Jow o/p when 

0-high Tx disabled. 

1 - loopback (connect o/p to i/p) 
a sync 


0- normal Tx 
1 - Send a break 

0-Tx enabled < *9 

1 - Tx disabled after last char sent 
0- Disable Tx 

1 - Enable Rx when Tx disabled after last char sent 

0 -Tx status register read * 10 

L - word transmitted and Tx buffer empty 

0 - Tx buffer read . * 9 

1 - Tx word transferred to Tx shift register 
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RECEIVE STATUS REGISTER 


BF 


hhhl 


OE 


PE 


FE 


F/S 


M 


SS 




(rsr = $FFFA2B) 


RE 


0 - disable Rx and clear flag 

1 - enable normal operation 

0 - strip sync character (sync) 

1 - send sync character Generates 

0 - stop bit Rx (asy nc ) j nterupt 

1 - word being Rx 

O-nocharmatchCsync), no break(async) \\ 

1 - word match , break Rx 

0 - no frame error in word in Rx buffer (async) 

1 - Frame error in Rx buffer word 

0 - no parity error in word in Rx buffer j ] 

1 - parity error in Rx buffer word 

0 - Rx status register read . 12 

1 - word received and Rx buffer full 

0 - Rx buffer read Read jj 

1 - Rx word transferred to Rx buffer only 
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MC6850 ASYNCHRONOUS COMMUNICATIONS 
INTERFACE ADAPTOR 



DG-D7 



Tx data 


CTS 

DCD 


RTS 


Rx data 


The MC6850 AC I A provides data formatting and control of a serial interface to an 
8-bit bidirectional data bus. At the bus interface, the four AC I A registers, the status 
and receive data (read only) and the control and transmit data (write only) registers* 
appear as two addressable memory locations. 


The programmable ACIA control register, which sets the format of the serial link, is 
located at &FFFCOG (16776192) for the intelligent keyboard serial communications 
link, and at SFFFC04 (16776196) for the MIDI interface. 

The ACIA supports peripheral/ modem control through: 

RTS request to send, 

CTS dear to send, and 
DCD data carrier detect. 

Protocols for 8 and 9 bit transmission using an optional odd or even parity, and one 
or two stop bits, are available through the programmable control register. 

The MIDI port may be configured for a second serial port, but the intelligent 
keyboard interface is not accessible. 
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AC/A CONTROL! STA TUS REGISTER 


Interrupt request 
Parity error 

Rx overrun (characters lost) 
Framing error 
CTS 

DCD 


"READ* 
RECEIVE STATUS 
REGISTER 


Tx data register empty 
| Rx data register full 



$FFFCOO - $FFFC04 


0 0 j normal ) Divide 

0 1 > div 16 > select 

1 0 j div 64 j bits 

1 1 Master reset 


0 0 0 --> 7-bits even 2 stop bits 

0 0 1 — > 7 -bits odd 2 stop bits 

0 1 0 7-bits even 1 stop bit 

0 1 1 7-bits odd 1 stop bit 

10 0 --> 8- bits 2 stop bits 

1 0 I --> 8-bits 1 stop bit 

1 1 0 --> 8-bits even 1 stop bit 

1 1 1 — > 8 bits odd 1 stop bit 


0 

0 

1 

1 


0 RTS low Tx interrupt disable 

1 RTS low Tx interrupt enabled 

0 RTS high Tx interrupt disable 

1 RTS low Tx a break onto data 


'WRITE* 
TRANSMIT CONTROL 
REGISTER 

output. Tx interrupt disable. 


0_Rx interrupt disable 

1 _Rx interrupt enable (Rx data register full overrun. DCD low-to-high transition) 


g 




* 


Bj 3 

E 
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YM2149 YAMAHA PROGRAMMABLE SOUND 
GENERATOR 


Channel 

A 

Channel 

B 

Channel 

C 


Tone ■ 


Tone- 


Tone- 


Mixer 


Noise - 


X 


Envelope 

Generator 


/ 


/ 


Amp\— 
* 

D/A 


Amp^> — 

D/A 

Amp/ — 

TVA 


BLOCK DIAGRAM 


Sound 

o/p 

port 


CPU 

I/O 

REGISTER 

8-bit I/O 

bus 

CPU 

port A 
8 bit I/O 

I/O 

REGISTER 

bus 

portB 





The programmable sound generator control registers are located as follows: 


RAM offset 

Function 

Bits used 



ad dr 

Base addr $FF8 800- 16746596 

7 6 5 4 3 2 1 0 

0 

0 

Channel A fine tune 

xxxxxxxx 

I 

1 

Channel A coarse tune 

X X X X 

2 

2 

Channel B fine tune 

xxxxxxx x 

3 

3 

Channel B coarse tune 

X X X X 

4 

4 

Channel C fine tune 

xxxxxxxx 

5 

5 

Channel C coarse tune 

X X X X 

6 

6 

Noise period 

X X X X X 

7 

7 

Mixer controLT/O enable 

I/O noise tone 

Fixed amplitude 

8 

8 

Channel A amplitude 

M x x x x 

9 

9 

Channel B amplitude 

M x x x x 

10 

A 

Channel C amplitude 

M x x x x 

Variable amplitude 

11 

B 

Envelope period fine 

xxxxxxx x 

12 

C 

Envelope period coarse 

xxxxxxxx 

13 

D 

Envelope shape 

C R A H 

14 

E 

I/O port A (output only) 


15 

F 

I/O port B (centronics) 

data 


M = mode fixed/ variable* C = cycle. A = alternate, x = bits used. R = ramp, H = hold 
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DIRECT MEMORY ACCESS CONTROLLER (DMA) 



+5v 

clkSMhz 

RDY 

ACK 

CDO 

CD1 

CD2 

CD3 

CD4 

CD5 

CD6 

CD7 

grid 

CA2 

CA1 

CRAV 

HDGS 

HDRQ 

FDCS 

FDRQ 


MEMORY MANAGEMENT UNIT (MMU) 


D4 

1 

68 

D3 

D5 

2 

67 

D2 

D6 

3 

66 

D1 

D7 

4 

65 

DO 

16Mhzdk 

5 

64 

MAD9 

CASOM 

6 

63 

MADS 

CASOL 

7 

62 

MAD7 

RASO 

8 

61 

gndB 

latch 

9 

60 

MAD6 

+5v 

10 

59 

MAD0 

A 16 

11 

58 

MAD1 

A17 

12 

57 

MAD2 

A18 

13 

56 

MAD3 

AI9 

14 

55 

MAD4 

A20 

15 

54 

MAD5 

A21 

16 

53 

dtack 

LDS 

17 

52 

DE 

RASI 

18 

51 

vsync 

4Mhzclk 

19 

50 

Al 

mhzdk 

20 

49 

A2 

CASIL 

21 

48 

A3 

CASIM 

22 

47 

A4 

W/E 

23 

46 

A5 

DMA 

24 

45 

A6 

WDAT 

25 

44 

+5v 

UDS 

26 

43 

A7 

gnd A 

27 

42 

AS 

CPMCS 

28 

41 

A9 

DCYC 

29 

40 

A10 

RDAT 

30 

39 

All 

DEV 

31 

38 

A 12 

AS 

32 

37 

A13 

RAM 

33 

36 

A14 

R/W 

34 

35 

A15 


1-33 


VIDEO CONTROLLER (SHIFTER) 



+5v 

dk 16Mhz 

CS 

DE 

hi 

A2 

A3 

A4 

A5 

R/W 

Mono 

RO 

R1 

R2 

GO 

G1 

G2 

BO 

BI 

B2 


GENERAL HOUSEKEEPING (GLUE) 


+ 5v 

1 

68 

A13 

A14 

2 

67 

A12 

A15 

3 

66 

All 

A16 

4 

65 

A10 

A17 

5 

64 

A9 

A18 

6 

63 

AS 

A19 

7 

62 

A7 

A20 

8 

61 

A6 

A21 

9 

60 

A5 

A22 

10 

59 

A4 

A23 

11 

58 

A3 

AS 

12 

57 

A2 

FC2 

13 

56 

A1 

FC1 

14 

55 

R/W 

FC0 

15 

54 

elk 2Mhz 

VMA 

16 

53 

SNDCS 

ROM4 

17 

52 

grid 

ROM 3 

18 

51 

MFPCS 

ROM2 

19 

50 

LACK 

ROM 1 

20 

49 

D1 

ROMO 

21 

48 

DO 

reset 

22 

47 

UDS 

RAM 

23 

46 

LDS 

DMA 

24 

45 

EGO 

DEV 

25 

44 

MPPINT 

PCS 

26 

43 

dk 500Khz 

BGI 

27 

42 

6850CS 

RDY 

28 

41 

BGACK 

VPA 

29 

40 

BR 

Berr 

30 

39 

DE 

dtack 

31 

38 

vsyne 

IPL1 

32 

37 

hsync 

IPL2 

33 

36 

blank 

SMhzclk 

34 

35 

gnd 


Chapter 2 

The operating system 
(TOS) overview 
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Operating system overview 

The Atari ST operating system is in many ways functionally similar to CP/M 68K, 
with extensions for handling a mouse , sound, the midi interface* an intelligent 
keyboard and joysticks, A graphics environment manager (GEM) provides ad- 
ditional single-user support for windows and communications via VDI and AES 
extensions, which accomodate graphics and an applications environment. Program 
transportability is maintained by splitting the operating systems into machine 
independant (BDOS, VDI and AES) and machine dependant basic input/output 
utilities (BIOS and A-line routines). 

The ST programmer is given access to the VDI primitives via the A-line routines 
for much greater graphic application speed. 

The disk operating system (DOS) enables routines to access the disc drives with 
support for existing single user programs, file locking to ensure safe updating, read 
only and unlock facilities. The access manager improves the file handling with a 
library of routines that permit indexed files through a tree structure to ensure high 
operational efficiency. Other functions available are; both data and indexed file 
system initialization update, duplicate keys and an index file search. Runtime errors 
may be handled internally, or there is the option to stop and correct the error. 


Machine 
dependant 
input/ouput 
routines , 


General 

operating 

systems 



Programmable segments of TOS 


The application environment (AES) multi tasks using a timeslicing technique and 
supports a database file management system, real time data aquisition, communi- 
cations and process control. 


The virtual device interface (VDI) allows the use of peripheral independant device 
drivers and provides a high degree of assistance for advanced user interfaces* 
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BASIC INPUT/OUTPUT SYSTEM (BIOS) 

The BIOS consists of all the machine dependent I/O routines of Digital Research’s 
GEM and additionally provides access to the A-line routines for fast graphics. The 
I/O functions can be categorized as follows: 

GEM BIOS: 

System I/O: 

Parameter block initialization 
Console I/O: Data I/O & query 
Disk I/O: Memory/disk transfers 

Atari ST extended BIOS: 

Port I/O: Configure RS232, mouse, midi & sound port 
Screen I/O: Get screen parameters 
Disk I/O: Memory /disk transfers 
Keyboard I/O: Keyboard communications 

A-line routines: 

Pixel graphics 
Line graphics 
Sprite graphics 
Bit block transfer 
Mouse handler 
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BASIC DISK OPERATING SYSTEM (BDOS) 

The disk operating systems permits the machine independent routines to access the 
disk drives and handle file management through the following functions: 

Set/get time and date 
Tree directory management 
File attribute management 
Create/open/close files and disk transfers. 


Virtual device interface 

1 he VD1 provides a set of graphic function calls that allow portability across 
physical hardware. Not all the standard VDI calls are implemented on the ST, the 
\ DI tables Chapter 3 are annotated to show those that arc missing. 


Control I/O: 
Graphics I/O: 
Attribute I/O: 
Raster I/O: 
Input I/O: 
Inquire I/O: 
Special I/O: 


Initialize graphics & set defaults. 

Primitives, lines, polygons, bars, arcs & pics. 
Set colour and style. 

Bit block transfers, fill, font and cursor forms. 
Key board /mouse interaction with console. 

Get attributes, resolution, style etc. 

Permits specialized functions to be performed. 


The AES (application environment services) are a series of utilities that handle 
graphic based inputs to the user application. For example, instead of asking for 
INPUT - the screen displays graphically a menu of options which may include a 
clock, a file and perhaps a disk, these items being given a pictorial representation 
that is called genetically an ‘Icon’. To select one, the user simply moves the cursor, 
which may look remarkably like an arrow, and places it on the required icon using 
the mouse and presses the trigger button. The AES routines are put into groups 
called libraries as follows: 


AES Libraries: 


Application: 

Provide access to AES routines. 

Event: 

React to user inputs. 

Menu: 

Translate defined text to menu format. 

Object: 

Substitute graphic icon for its label. 

Form: 

Handle text inpu; automatically when needed. 

Graphic: 

Primitive graphic functions. 

Clipboard: 

Management of cut and paste. 

File Selector: 

Creation/di splay of user selected file. 

Window: 

Handle windowing of queried input responses. 

Resource: 

Interface device dependant drivers to applications. 


Application programs 

The desktop application provides the support for windowing, control and synch- 
ronization of asynchronous events, interprocess communications, loadable device 
drivers and device independant graphics support. The clock application date stamps 
each file on creation or modification. 
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MEMORY ALLOCATIONS 


ATARI MEMORY MAP 


FFFFFF 


FF880D 


FA0000 


1O00OO 


080000 


000800 


000400 


000000 


Memory 

mapped 

input/ 

output 


ROM 

Area 


1024K 

RAM 


512K 

RAM 


OSBSS 
user RAM 
variables 


Supervisor 

RAM 

variables 


16777215 


16746596 


16384000 


1048576 


524288 


2048 -| 


FFFFFF 

FFFC00 

FFFA00 

FF8800 

FF8600 

FF8400 

FF8200 

FF80O0 


MC6850 


MK 68901 


SOUND 


DMA/Disk 


Reserved 


Display 


Memory 


16777215 

16776192 

16775680 

16746596 

16746084 

16745572 

16745060 

16744448 


Memory mapped I/O 
Configuration Registers 


1024 


Supervisor 
access only 


FF0000 


FC0000 


FA0000 



16711680 


16515072 


16384000 


ROM configuration 
in memory 


References to the bottom 2K of memory and the I/O space are classed as supervisor 
references and attempted access from user mode will cause an error exception trap. 


n » 


t :: 


$800 

$400 

$200 

$100 

$0BC 

$0B8 

$0B4 


$08C 

$088 

$084 

$080 


$070 

$06C 

$068 

$064 

$060 


$03C 


$02C 

$028 

$024 

$020 

$01C 

$018 

$014 

$010 

$00C 

$008 

$000 








Trap #15 vector 

Trap #14 vector 

Trap #13 vector 

Trap #12 vector 


Trap #3 vector 

Trap #2 vector 

Trap #1 vector 

Trap #0 vector 

Int level 7 

Int level 6 

Int level 5 

Int level 4 

lot level 3 

Int level 2 

Int level 1 

Spurious Int 




Uninit int vector 



Emulation 1111 

Emulation 1010 

Trace 

Privilege violation 

Trap instruction 

CHK instruction 

Zero divide 

Illegal instruction 

Address error 

Bus error 

Initialise PC 

Reset ink SSF 


SYSTEM TABLES 


Operating system block 
storage segment 


System parameters and 
1024 1 variables 

512 rese r ved for OEMs 


256 

192 

188 

184 

180 

176 

140 

136 

132 

128 

124 

120 

116 

112 

108 

104 

100 

96 


60 

48 

44 

40 

36 

32 

28 

24 

20 

16 

12 

8 


MFP vectored interrupts 


Atari ST BIOS extensions 
GEMBIOS 


BDOS 

GEMDOS interface 

Non maskable interrupt ft** 
MK68901 MFP L 

Vertical blank sync 
Normal interrupt level 
Horizontal blank sync 


Unused vectors point to 
system critical error handler. 


Used by some AES functions 
A-line routines entry 

The system variables are in 
the supervisor space and can 
be accessed only in supervisor 
mode. 


Supervisor 
* space 




0 


2-8 


CONFIGURATION REGISTERS 

Functions controlled 

FFFFFF 
FFFCOO 
FFFAOO 

FF8800 

FF8600 
FF8400 

FF8200 
FF8000 


ACIA 


MFP 


Sound 


DMA/disk 


Reserved 


Display 


Memory 


10 / / I LLJ 


16776192 


16775680 


16746596 

16746084 

16745572 

16745060 

T 


Keyboard and 
MIDI I/O 

System clocks 
System interrupts 

PSG 3 channel sound, noise 

tone, amplitude and envelope 

RS232 

Parallel port 

Disk write 

Floppy/hard disk 
DMA 


Video address 
Field rate 

Video mode & pallette 
Memory size 
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Resource management overview 

The pseudo multitasking kernal can support one primary application and one of 
three desk accessory programs. 

The main application may be GEM or DOS such as GEM desktop application or a 
word processing package etc. 



A minimum space 
allocation of 128K, 


A desk accessory is an application that does not take over the entire display screen, 
running in a specially designed window. The calculator is a typical accessory. 

Only one desk accessory program may be active at a time, and will only load if at 
least 128K of RAM is left for the primary application. 

CPU resources 

The dispatcher divides CPU time between primary applications and background 
processes. These jobs are put into lists; ‘Ready for processing’ and 'Not ready', and 
are serviced on a round robin schedule with the current process at the head of the list 
running. Not ready processes may be waiting for a key press, mouse movement or 
trigger, time lapse etc. 



:1 

:1 
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Graphics Concept Overview 

The Atari ST graphics is supported at a primitive level through the A-line routines 
and at a higher level through a limited version of the Digital Research graphic 
system extension (GSX), which is based on the ANSI virtual device interface 
(VDI). VD1 provides a set of graphic primitives (GDOS) and a library of device 
drivers (GIOS) for the preparation of transportable software. The whole of GDOS 
does not form part of the ST operating system and there is no support for 
‘normalized device coordinates’ based on a 32K * 32K screen, or a small number of 
the VDI functions. 

The VDI interface provides output primitives of lines, arcs, polygons etc. and input 
primitives to point symbolically, get co-ordinates of joystick/ mo use or keyboard 
input etc. It also supports the control of multiple output devices using raster 
screens. 

The A-line routines give very fast access to the primitive pixel, line, sprite and bit 
block transfer graphic functions at the expense of portability 

The Raster co-ordinate graphics are based on screen pixels: 


0,0 


640,400 


GEM programs arc portable but must take into account two possible problem areas: 

Screen aspect ratio: Different hardware systems and displays (screen, printer, plotter 
or another computer) may have different aspect ratios. Producing similar screen 
designs requires the programmer to scale the data sent to the display device using 
the aspect ratio returned from the open workstation call. 

Language implementations: Different language implementations of a program will 
require different length text strings to be fitted into windows. The inquire character 
cell width call in conjunction with the window size returned by the wintLget call will 
enable the programmer to determine the number of characters acceptable. 

Alert and Dialog boxes have predetermined responses set up using the resource 
construction set and therefore do not present a language problem. 

The missing part of GDOS is available as part of the code supplied in certain Digital 
Research products and may at a later date become more generally available for the 
ST. On this premise, the details of the missing parts are given coupled to a rider that 
theyt are not available on the basic system. 
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J 
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GEM usually provides two graphic coordinate systems to the programmer, raster 
and normalized. 

Raster is based on the computer’s screen resolution, in the case of the Atari ST 
600 x 400 pixels. 

Normalized is based on a notional screen of 32767 x 32767 points, the points being 
translated to the actual screen of the target system by one of the GIOS device 
drivers. The idea behind this is to write software independant of specific screen 
resolutions. 



Normalized device co-ordinates are based on a screen of 32767 x 32767 pixel 
dimensions. 



0,0 


32767,32767 


Graphic Co-ordinate Computation 
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OVERVIEW OF SCREENS 

The Atari ST screen may be operated in three different resolution modes, the 
colours may be chosen from a pallette of 5 12 colours: 

High: 640 x 400 pixel, black and white display 

Medium: 640 x 200 pixel, 4 colour display 

Low: 320 x 200 pixel, 16 colour display 


High Resolution 640 x 400 pixels 


origin 

single 

plane 




ysySs Black border 


No colour, inverse video is available deter- 
mined by the condition of bit zero of pallette 
colour zero. 


D 


Medium Resolution 640 x 200 pixels 

origin 


two 

planes 


Only first 4 pallette table lookup entries are 
available. 




Border pallette colour zero. 


* : 


Low Resolution 320 x 200 pixels 

origin 


four 
planes 




16 word lookup pallette table 9 bits per entry, 

3 red, 3 green and 3 blue on low nibble 
boundaries, giving 8 x 8 x 8 possible colours, 
(512) 


Border pallette colour zero. 


ii 


ii 


Ml 


It is not possible to change resolution while using GEM 


■ as t 


i 


2-13 


Colour Pallette Table 


) 


Pallette colour 


Pallette colour 
zero, bit zero 



15 12 11 8 7 4 3 0 



Colour nibbles 


Physical to logical screen transposition 


4 


Physical Screen 


1 

2 

3 1 , 

1 i$J 11 \ 

641 

642 

pixels 


bit 15 


bitO 




MSB word 1LSB 

MSB word 2 LSB 

MSBword41 LSB 


ards 


& 

o 

o 

40 words 



I MSB word 16000 LSB 




Border always 
set black 


High Resolution 
Mode 640 x 400 


Low Memory 



Screen in memory 


High Resolution Screen 


Bit zero of the colour pallette 
provides inverse video. 
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Physical Screen 


1 

2 

641 

642 


ZI 


pixels 


Medium Resolution 
Mode 640x200 

OJ 

G 

E Low Memory 
1 word 1 


MSB word 1 


Plane 1 

LSB | MSB word 3 


Plane 2 


L 


MSB word 2 LSB [ MSB word 4 m 

200 words 

80 words — — — 4- - -W 

▼ ! 

j MSB word 160Q0LSB \ 


< ~ ~ 


V7777, 


15 


13 


y Bor der Set by colour pallette zero 
0 


2 1 


Plane 1 word 
Plane 2 word 


Colours generated by 
interleaved bits of words 


word 2 


High Low 


word 1 5999 


word 16000 


Screen in 
Memory 


Plane 

Pallette 

1 2 

colour 

0 0 

0 

0 1 

1 

1 0 

2 

1 1 

3 


a : 


a « 


5c* 

S 


4 ) 


191 i 


Physical Screen 


1 

2 

321 1 

I 322 


T T 


1 8 | 9~ 


pixels 


MSB word 1 LSB I MSB word 5 
— \ V 


MSB word 2 LSB | MSB word 6 

\ J — V 


MSB word 3 


LSB MSB 


-Plane 4 


MSB word 4 


LSB | MSB 

A 

200 words 

— 80 words — — — — ^ ^ 

, i— i 

UV1SB word 16000 LSB | 




Border Set by pallette colour zero 


Low Resolution 
Mode 320x200 



Bit 

:V 


Pallette 


plane 


colour 

1 

2 

3 

4 

No. 

0 

0 

0 

0 

0 

0 

0 

0 

I 

1 

0 

0 

1 

0 

2 

0 

0 

1 

I 

3 

0 

I 

0 

0 

4 

0 

1 

0 

1 

5 

0 

I 

1 

0 

6 

0 

1 

1 

1 

7 

1 

0 

0 

0 

8 

1 

0 

0 

1 

9 

1 

0 

1 

0 

10 

1 

0 

i 

1 

11 

1 

1 

0 

0 

12 

1 

1 

0 

1 

13 

1 

1 

i 

0 

14 

1 

1 

l 

l 

15 


**»! 


it in iri m _m. 
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Colour generation 

A word from each plane is taken from the video display file and placed in the video 
shift register from where the bits are collectively used to index into the colour 
pallette table. The colour code generated is supplied to a 3-bit digital to analogue 
convertor to produce the RGB signals. 

Video display Colour pallette 

Logical bit- map memory Video and 3 -bit 

planes shift regi ster D AC s 



In high resolution monochrome mode, the video shift register passes its data to the 
inverter and not the pallette lookup table. 


COLOUR CHANGING 

To prevent jitter when changing colors using the Hblank ($068) and Hsync (3120) 

interrupt vectors, programmers should use the following procedure: 

1 Revector keyboard/MlDI interrupt to a routine that lowers the IPL to 5 and 
then jumps through the original vector, 

2 During the critical section of screen, revector the system 200Hz clock interrupt 
vector to a routine that increments a counter and then RTEs. 

3 After the critical section, block interrupts (at IPL 6) and call a system clock 
handler that jumps through the interrupt vector with a fake SR and return 
address on the stack, the number of times indicated by the counter. 


Animation 

Animation is most easily achieved by switching alternately between two screens; one 
on display, the other being updated in the background. Initially write two identical 
screens and display one while modifying the other, swap the screens over and 
display the modified screen while updating the one previously on display. The 
technique will produce a very stable display with quite slow switching rates. 
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Sound 


SOUND CONCEPT OVERVIEW 

Sound is generated via a Yamaha YM2149 programmable sound generator. The 
PSG contains three tone generators that produce the basic square wave tone 
frequencies for the A, B and C channels and a noise generator, that produces a 
frequency modulated pseudo random pulse width square wave, which may be 
combined with the tone generator outputs using the channel mixer. The output level 
can be fixed via the channel amplitude control using one of the three sixteen level 
D/A converters or varied by using the output of the envelope generator, which may 
be used to amplitude modulate the output of each mixer. 


Sound control registers 

The frequency of each tone generator (30Hz to 125KHz) is obtained by counting- 
down the I2“bit value of the tone registers (the coarse register sets the upper 4 bits 
and the fine register sets the lower 8 bits, range 00 1H to FFFH (1 to 4095). The 
standard PSG format is to produce a lower note for a higher count whenever a 
register count-down is performed. 

The noise generator frequency is controlled by a 5-bit noise period register, value 
01H to 1FH (1 to 31), producing a frequency range of 4Khz to 125Khz. 

The mixer control register is a multi- function register that mixes the noise channels 
(defined by bits 3 to 5) and the tone channels (defined by bits 0 to 2) in all possible 
combinations to the input/output ports (bit 6 I/O, bit 7 port A or B). 

The amplitude of a channel is controlled to one of sixteen fixed levels by the channel 
D/A converter register (lower 4 bits of the register) and only by setting the register 
to zero can the channel be turned off. The fifth bit of the amplitude control register 
is set to select the variable level output defined by the envelope generator. 

The envelope generator comprises three registers, two provide the frequency 
variation and the third the format of the envelope. The frequency is determined by 
counting down the 16-bit value of the coarse and fine envelope registers range 
000 1H to FFFFH (1 to 65535). The shape and cyclic pattern of the envelope is 
defined by the lower 4 bits of the shape register (the amplitude register setting the 
level), the four bits provide for combinations of hold/cyde, reverse cycle on/off, 
ramp up/down and cycle hold pat tern/ re set to zero* 

Parallel data I/O 

The I/O register in the PSG is not associated with sound production, it provides a 
register to transfer 8-bit parallel data to and from the CPU bus to the I/O port A, 
there is no affect on any of the PSG’s other functions. 
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Data is written to a peripheral device from the bus using the following steps: 

Select enable register (mixer register) 

Set bit 6 to f l 3 (set I/O port A to output) 

Select I/O port A data store (I/O port A register) 

Write data to PSG (write data to I/O port A register) 

Once data has been loaded into the register, the data remains until further data 
is loaded, the system is reset, or 

the register is switched to input mode. 

Data is read from a peripheral device to the bus with the following steps: 

Select enable register (mixer register) 

Set bit 6 to (set I/O port A to input) 

Select I/O port A data store (I/O port A register) 

Read data from PSG (read data in I/O port A register) 

The register follows signals applied to the port, only by reading will the data 
be transferred to the bus* 
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SOUND CONFIGURATION REGISTERS 

Access to the PSG should be in supervisor mode as the SR register is modified. The 
PSG registers are located for write at address(8FF880O - 16746596) as follows: 


0//ser 

Hex Dec 

0 

SO 

Channel A fine tune 

(8 bit) 

1 

$i 

Channel A coarse tune 

(4 bit) 

2 

$2 

Channel B fine tune 

(8 bit) 

3 

$3 

Channel B coarse tune 

(4 bit) 

4 

84 

Channel C fine tune 

(8 bit) 

5 

85 

Channel C coarse tune 

(4 bit) 

6 

86 

Noise generator control 

(5 bit) 

7 

87 

Mixer control * I/O enable 

(8 bit) 

8 

88 

Channel A amplitude 

(5 bit) 

9 

89 

Channel B amplitude 

(5 bit) 

10 

$A 

Channel C amplitude 

(5 bit) 

11 

SB 

Envelope period fine tune 

(8 bit) 

12 

8C 

Envelope period coarse tune 

(8 bit) 

13 

8D 

Envelope shape 

(4 bit) 

14 

8E 

I/O port A 



Tone frequency calculations (registers 0 to 5) 

The tone frequency is in the range 30<5Hz to 125Khz and may be calculated from 
the formula: 

F" 2 x 10 6 

16 x (256 x CT + FT) 

where CT = coarse tone period 
FT = fine tone period 

Noise frequency calculations (register 6) 

The noise frequency is in the range 4Khz to 125Khz and may be calculated from the 
formula: 

F= 2 x 10 6 


^ 1 


si 




■ 


I) 


111 


mi i 



3 

1 

3 

1 

1 

J 

3 
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3 

3 

3 

3 
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The mixer controM/G enable 
(register 7) bit functions 
take the following format: 


The channel amplitude 
(registers 8- 1 0) bits have 
the following function : 


0 1 2 

3 4 5 

6 7 

Tone 

Noise 

HO 

channels 

channels 

port 

ABC 

ABC 

A B 

If the bit is zero 

If bit 0 

the channel is on. 

port i/p 


M = 0: Fixed amplitude level 
0-low to 15-high (xxxx) 

M = 1: Amplitude determined 
by envelope shape 


Envelope shapes 

The envelope period (registers 11 & 12) of the shape is based on the 16-bit register 
value: 


flock 

256 x Ep where Ep = envelope period 

fdodt = input dock frequency 

The envelope shape/ cycle control (register 13) bit settings produce the following 
range of sound envelopes: 


0 

Bus 
I 2 

3 

Function 

0 

Bits 
1 2 

3 

Function 

X 

X 

0 

0 

\ 

1 

1 

0 

1 

\i 

X 

X 

I 

0 

A 

0 

0 

1 

I 


0 

0 

0 

1 

VsNNWNN 

i 

0 

l 

1 

/ 

i 

0 

0 

1 

\ 

0 

1 

1 

l 

A/WW 

0 

1 

0 

1 

V'N/'VN/V 

1 

1 

I 

I 

A 


Bit 0 = Hold/cycle Bit 2 = Ramp up/down 

Bit 1 = Reverse on/off Bit 3 - Cycle hold/reset zero 


i — bit set 
0 - bit clear 
x = don't care 


16 x Np 

where Np = noise period 
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GEM disk operating system overview 

For those systems supplied with the operating system on disk; the system disk 
contains on the first two tracks, a cold start loader that loads the operating system 
image file (TQS.IMG) into high memory and then block loads it down into RAM 
memory at address $5000. 

The TOS image file contains both the GEM and Atari ST extended operating 
systems, including: 

CCP Console command processor; User interface to parse command line 
BDOS Basic disk operating system: Access functions to the file system 
BIOS Basic IjO system: Functions that interface peripheral device drivers 

The operating system is always in memory above $400 and all modules reside 
permanently in memory, even those of disk based systems (unless the power is 
removed). After TOS is loaded, the remaining contiguous address space is called the 
transient program area (TPA) where TOS loads executable (command) files. The 
command files (programs) should not access absolute addresses or default TOS 
variables but use the BIOS and BDOS function calls. 

Each transient program loaded into memory consists of the program segments (text, 
data and bss), a user stack and a base page. The 256 byte base page contains the 
direct memory address (DMA) buffer, at base page offset $80; the buffer contains 
the command tail, typically the input typed to an application installed as a TOS 
Takes Parameters program. Before the loaded program takes control, the address of 
the transient programs base page and a return address are pushed onto the user 
stack, 4(A7) and (A7) respectively. 

Although the CCP can only load one program; the transient program itself can load 
further programs using GEMDOS function $4B, but must specifically supply the 
base 

A return from a transient program may be achieved by: 

An RTS as the last statement, returning via the return pushed onto the stack by 
the load function. 

Executing a warm boot by calling extended BDOS function 0. 

Typing ctrl c from the console during the execution of console output, printing 
a string or reading from the console buffer (functions 2, 9 and 10). 


if t 
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GEMDOS Memory model 
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High memory 


Command file 

The format of a command file is that of a header, two program segments (text and 
initialized data segments) and optionally a symbol table and relocation information. 
After the program is linked and loaded into memory, it contains additionally a 
zeroed uninitialized data (BSS) program segment and starts execution at the 
beginning of the text segment. 

Not all assemblers provide for an uninitialised data section within the source code, 
this results in an executable program file on disk that is much larger than need be. 

The operating system holds information on the data segments in a descriptor block 
(256 byte base page data structure) at the bottom of the TPA. The base page does 
not reside at a fixed address, its position is determined when it is created by the load 
a process function (GEMDOS function #$4B) and held in register D0.L. 

The base page contents are initialized by the GEMDOS load function: 


Base page format initialized by GEMDOS 


800 


0 

804 


4 

$08 


8 

80C 

810 


12 


16 


814 

20 


818 

24 


81C 

28 


Base address of TPA 
End address of TPA 4- 1 
Base address of text (code) 

Length of text (code) 

Base address of initialized data 
Length of data 

Base address of BSS uninitialized data 
Length of BSS uninitialized data 
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There are slight differences between small sections of the original CP/M 68K and 
GEM DOS base page formats as follows: 


CPIM 68K format 


$20 


32 

$24 


36 

$25 


37 

$38 


56 

$5C 


92 

$80 


128 




Length of free memory after BSS 
Drive from which program loaded 
Reserved by BDOS 
2nd parsed FCB from command line 
1st parsed FCB from command line 
Command tail and default DM A buffer 


Set 

by 

CCP 


GEMDOS format 


$20 


32 

$24 


36 

$28 


40 

$2C 


44 

$80 


128 



DTA address pointer 
Parent's base page pointer 
Reserved 

Pointer to environmental string 
Command line image (typically the entry to a 
dialog box for a TTP application) 


File header format 


GEMDOS file header and program segments take the format: 
File header 


$00 


0 

$02 


2 

$06 


6 

S0A 


10 

$0£ 


14 

$12 


18 

$16 


22 

$1A 


26 


Data and BSS contiguous 601 AH else 601BH 
Number of bytes in text segment 
Number of bytes in data segment 
Number of bytes in BSS 
Number of bytes in symbol table 
Reserved (zero) 

Start of text segment and prog execution 
Zero if no relocation bits 


If data and BSS are not contiguous (first field equals 601BH) 


$1C 

$20 


28 

32 


Start address of data segment 
Start address of BSS 


Note: 601 AH is a BRA , S instruction that bypasses the file header data segment 
The Atari OS does not support segmented files* 


The symbol table consists of fourteen bytes that specify a null padded 8-character 
name, the type of symbol and the sy mbol value (address etc). 


Hex 

Symbol type 

100 

200 

400 

800 

1000 

2000 

4000 

8000 

BSS } 

Text / relocatable 

Data / 

External reference 
Equated register 
Global 
Equated 
Defined 



Relocation table 

The tinker optionally produces a relocatable executable file and places the relocation 
information in the GEM file header. 


Type 

Son of address referenced (File header offset $la) 

00 

No relocation data required 5 absolute references 

01 

References relative to data segment base address 

02 

References relative to text segment base address 

03 

References relative to bss base address 

04 

References an undefined symbol 

05 

References the upper word of a longword, the next relocation word 


determines 'absolute' or ‘relative' 

06 

16-bit PC-relative reference 

07 

First word of an instruction not to be relocated 


Relocation word format 


0 

I 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 


— 1 M 1 ; 

Relocation Index value to a symbol in the 

word symbol table (starting at zero) 


If the offset byte is 1, then a multiple byte offset based on the following table is used 
to determine the actual offset: 


Offset 

byte value Relocation data 


$00 End of relocation data 

$01 Add 254 from current location and decode next byte 
$02 . . $FF Add byte value from current location 


When the program is loaded into memory at a location other than where it was 
linked, BDOS computes an offset and adds the offset to the address of the relocation 
words in the text and or data segments. 

GEMDQS function $4B (75 decimal) loads or executes a program. 


E? 

B 

m 

fr 

■ 

E 

E 

■ 

■ 
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ATARI ST FILE SYSTEM 

GEM contains a fairly comprehensive set of file manipulation facilities, they enable 
the programmer to write software that provides multiple access file sharing and file 
protection, periodic file updates and selective backups. The file facilities are: 


Code 

Dec Hex 

GEMDOS function 

Comments 

60 

3C 

Create file 


61 

3D 

Open File 

Invoked by filling a parameter block 

62 

3E 

Close file 

with the number of the function, the 

63 

3F 

Read a file 

parameters and any other relevant 

64 

40 

Write a file 

data. 

65 

41 

Delete file 

Returns are in DQ*L, 

66 

42 

Seek file pointer 

A zero indicates ok. 

67 

43 

Get/set attributes 


69 

45 

Duplicate file handle 

Where data is returned, DO contains 

70 

46 

Force file handle 

the address of the data return block. 

78 

4E 

Search for first 


79 

4F 

Search for next 

GEM uses the stack as the 

96 

56 

Rename file 

parameter block. 

97 

57 

Get/set date/time stamp 



4 
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ATARI ST DISK SYSTEM 

The Atari ST 3,5” disk uses soft sectored disks of the following format: 

Bytes /sector 512 
Sectors /track 9 
Tracks/side 80 
Sides/media 1 2 

Unformatted 360K 720K 

The GEM BIOS interfaces (Basic input/ output systems) make the hardware 
dependent interface to the floppy disk drives. These communicate with the drives as 
follows: 

Select the drive, the side, the track and then the number of sectors from the track 
that will be read to a buffer or written from the buffer to the disk. 

GEM BDOS is fairly basic in terms of disk operations but has extensions to handle 
tree type directories. 



Code 

GEM DOS function 

Dec 

Hex 


14 

0E 

Set default drive 

25 

19 

Get default drive 

54 

36 

Get drive free space 

57 

39 

Create a subdirectory 

58 

3A 

Delete a subdirectory 

59 

3B 

Set current directory 

71 

47 

Get current directory 


A file does not use consecutive disk sectors as there is insufficient time to identify, 
read and or write a record via software, and to locate a specific track via hardware. 
The record spacing (skew) is usually 6 sectors between adjacent file segments. 
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ATARI ST BIOS COMPARISONS 

The ST contains device dependant input/output utilities that handle the interface 
between the device independam routines and the hardware, the ST BIOS and GEM 
BIOS utilities are supplemented by the A-line primitives which provide rapid 
screen control. 

The GEM type BIOS handles the input/output to the peripheral devices: parallel 
port, RS232 port, console, midi interface and intelligent keyboard. There is also a 
basic disk read/ write to sector and a facility to check that the disk has not been 
removed or replaced. 

The ST extended BIOS also controls the input/output to the midi interface, 
intelligent keyboard, console and disk read/write, but additionally includes the 
control of a mouse, joysticks, sound and of the screen colours; the disk facility is 
augmented by format. 

The A-line routines are the VDI graphic primitives which are not program 
transportable and therefore included here, they enable control of the mouse and 
pixel-l in e-sprite-screen graphics. 


Interrupt handler overview 

The operating system provides the machine code programmer with access to the 
interrupt handler. 

Every fiftieth of a second control is transferred from the operating system to a 
routine at the address designated in the system variables at $68 (104 decimal), the 
system interrupt handler (vertical blank interrupts). The handler provides a timing 
facility, sets the screen parameters and current device driver installation and entry 
points. 
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System Initialization 

The ST in general follows a predefined initialization sequence on power-up^ with 
slight variations for the different operating systems. 


System reset 


ssp > $6Qxxxxxx 
pc -> SOOFC0O2Q 

The supervisor stack pointer (SSP) & 
program counter (PC) are set from $0 
and $4 respectively, the SSP is 
garbage until system is sized. The 

move.w #$2700 . SR 
reset 

cmpi .1 #$FA52235F , 
SFAOOOO 
bne cmpi_nxt 
lea $8 ( PC) , A6 
jnp SFA0004 

Interrupt priority level (IPL) is 
set to seven and a hardware reset 
executed. Checks for a diagnostic 
cartridge, if present causes 
a return address to be set in A6 and 
execution of the diagnostic routines 
commenced. 

cmpi . 1 #$31415926, 
$426 

bne psgset 
move,! $42A , 00 
tst.b 342A 
bne psgset 
btst #$0, DO 
bne psgset 
movea.l DO, A0 
lea $4(PC);A6 
j»P (A0) 

lea $FFFF88QO, AO 
move .b #$7 . (AO) 
move.b #$C0, $2 (AO) 
move . b #$E,(A0) 
move . b #S7,$2(AO) 
move . b #$0 , $FFFF32QA 
lea $ F F FF 8 2 40 , A 1 
move.w #$ F , DO 
lea $28A(PC) , AO 
move w [A0) + , (A1 ) + 
dbf DO. loop 

A check is made to see if memory has 
previously been sized. If not, 
jump past memory sizing routine. If 
this is a soft reset, the bailout 
vector may be valid. First check if 
the MSB is zero , secondly that the 
vector is to an even address, if not, 
jump past the reset handler . 

Set AO to point to the reset handler, 
set AS to the return address and 
jump to reset handler. 

Set AO to PSG configuration register 
base and set porta # portb to output, 
activate general purpose output and 
through output porta deselect the 
disks. 

Set sync mode to external 50Hz and 
A1 to base of pallette table. 

Set up a count in DO to shift the 
default hardware pallette colors to 
A0 which points to the default color 
table. 

move. 1 #$75201 9F3, 3420 
move . 1 #$237693AA, 343A 

Size both memory banks and perform a 
memory test. Set ' memory sized ' and 
' memory tested' flags in the system 
variables table. Set up screen. 

move . 1 #$8900, $432(A5) 

vblank Queue entries, BIOS entry 
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3 

3 

= 

3 

' 3 


lea $D50,A7 

point and supervisor stack. 

Run type *0* cartridge applications. 
Point A3 and A4 at RTF and RTS 
resply Test diagnostic cartridge. 
Initialise exception vectors to 
terminate process handler except for 

move.! rte,$14 

divide by zero which is RTE'd. 

move, 1 #$FCG324,$70{A5) 

Set vblank handler entry address. 

move,l rt e . $63 (A5 ) 

Kill hblank handler entry address. 

move.l rte,$88(A5) 

Initially empty trap§2 handler. 

move . 1 #$ F C03C0 , $ 84 ( A& ) 

Set up trap# 13 handler address. 

move.l #SFC03BA,SB8(AS) 

Set up trap#14 handler address. 

move.l rts, $40O(A5) 
move.l #$FC03B6 . $404(A5) 

Default timer tick vector to RTS. 


Set up the critical error handler 

move.l rts ,3408(45) 

and default the terminate vector. 

move.! #$550,$4A2(A5) 

Set up BIOS register save area 

suba. 1 A5,A5 

pointer Zero page pointer. 

suba.1 A5.A5 

Intialize vblank vector list. 

move.w $454(A5) , DO 

8 nvbls into DO 

lsl.w #2, DO 

multiply by four to 

move.w DO , D1 

create queue length in Dl. 

bsr make^spc 

Routine to create a space of 

and . 1 #$ FFFF . DO 8 

longwords in high memory. 

btst #30.00 

make 

beq jump! 

address 

addq.w #61 .DO 

even 

movea.l $436, A0 

current memory top 

suba . 1 DO, AO 

'come on down * 

move.l AO, 3436 

reset memory top 

move .1 A0 f D0 

and put in DO 

rts 

move.l A0, $456 (A5) 

vbl queue start address 

subq #31, D1 

zero 

clr.b (AQ)+ 

the 

dbf Dl ,clr_byte 

queue 


Initialize screen resolution. 
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move.w #$F8FF.$R Enable all interrupts except Hblank 

by setting I PL to 3. 

Run type *V cartri dge app Heat ions 
Initialize GEMDQS - set up a DOS 
disk buffer chain & mmry manager. 
Run type ' 3 ' cartridge applications 
Attempt to boot From floppy and 
execute if successful, if not poll 
devices on DMA bus for logical boot 
sector zero, execute if success fuL 
Any * returns* continue polling the 
devices in sequence. 

Turn on the cursor. 

Execute file COMMAND. PRG? 
otherwise construct a default 
envi content and execute AES. 

Initiate a RESET on a return . 
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CARTRIDGE SOFTWARE 


There are two types of cartridge which may be plugged into the ST; diagnostic and 
program cartridges. The cartridge program header format is as follows: 


Base address 
$FA0000 (16384000) 


$0 


$4 

$8 


$C 

$10 

$12 

$14 

$18 


OF LAG 


C-NEXT 


OINIT 


ORUN 


C-TXME 


C-DATE 

OBSIZ 


ONAME 


0 Only the first header contains a flag which denotes the presence 
of a cartridge. 

flag: #$FA52255F = diagnostics 
#$ABCDEF42 = program/data 

4 Pointer to next application header, a null indicates no additional 
applications. 

8 Pointer to application initialization code, if zero there is no 

initialization code. The longword high byte is unused in the 24 bit 

address and starts applications as follows: 

bit 0-set run before interrupt vectors and memory initialized. 

bit 1-set run before GEM DOS initialized. 

bit 2 unused 

bit 3-set run before disk boot* 
bit 4 unused 

bit 5-set Application is a desk accessory 

bit 6-set Application not a GEM application (no AES calls) 

bit 7-set Requires command line parameters before execution. 

1 2 Pointer to application entry point. 

16 Time \ 

v DOS format time and date stamps. 

18 Date y 

2 0 The size of th e applications B S S segmen t a 1 location . The O S 
must allocate the BSS before invoking any run code. Set to zero 
if not applicable. 

24 The ASCII name (max 1 2 chars) terminated with a zero 

(NNNNNNNN . EEE). 


Diagnostic cartridge: The ST hardware will not be initialized and a return address is 
held in A6> the stack pointer is trashed. The cartridge software is responsible for 
sizing memory and setting the hardware registers as required. 

Cartridge software : Application headers are strung together in a linked list, so there 
may be any number of applications on one cartridge. 
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BOOT SECTORS 

To write software that will auto run from disk, the programmer must produce a boot 
sector that contains a loader program which transfers the program from disk to 
memory before bringing up GEM, 

The boot sector follows IBM PC format and contains: 

The volume serial number 

24 bit number generated when the media is formatted 

BIOS parameter block (BPB) 

Sector size in bytes 

Number of sectors/cluster 

Cluster size in bytes 

Length of root directory in sectors 

Size of a File Allocation Table (FAT - in sectors) 

Sector# of start of second FAT 
Sector# of first data sector 
Number of data clusters on disk 
Flags 

Optional boot code and boot parameters 

During initialization the boot sector is loaded into a buffer and the executable boot 
sector code tested for a word checksum of #$1234* If satisfactory a subroutine jump 
is made to the beginning of the position -independent code in the buffer. 

When a get BIOS parameter block call is made, the BIOS reads the boot sector 
(normally created when the volume is formatted), and returns an error indication if 
any critical parameter fields are zero. 

The 24- bit volume serial number, written when the media is formatted, is used to 
determine whether or not a disk has been changed. 

The protobt extended BIOS call (dec IS) is used to create the boot sector (see 
chapter 3), which is written to track 0, side 0, sector 1 . 


BIOS boot parameter block 

(normally written when the volume is formatted) 


Note: word storage is low byte at the low address (even) as per 8086 and not the 
usual 68000 mode. 

The BIOS parameter block is compatible with MS-DOS version BPB, but will only 
read and write sectors written by another WD1772A disk controller. 
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£ 

£ 

£ 

£ 


3 

3 

3 

! 

w 

3 


$0 

BRA.S 

0 

Branch to boot code 

$2 

oems-space 

2 

Space reserved for OEMs use 

$8 

Volume serial# 
#$000000 

8 

24~bit volume serial number 
(used to determine disk changes) 

$B 

BPS 

$00 #$02 

11 

Number of bytes/sector 

$D 

SPC 

#$02 

13 

Number of sectors/cluster 

$E 

RES 

#$01 #$00 

14 

Number of reserved sectors 
(at start of media inch boot) 

$10 

NFATS 

#$02 

16 

Number of file allocation tables 
on media. 

$11 

NDIRS 
#$70 #$00 

17 

N umber of directory en tries 

$13 

NSECTS 
#$D0 #$02 i 

19 

Number of sectors on media 
(including reserved) 

$15 

MEDIA 

#$F8 

21 

Media descriptor - not used by ST 

$16 

SPF 

#$05 #$00 

22 

Number of sectors/FAT 

$18 

SPT 

#$09 #$00 

24 

N umber of sectors/track 

$1A 

N$IDES 
#$01 #$00 

26 

Number of sides on media 

$1C 

NHID 
#$00 #$00 

28 

Number of hidden sectors-not used 

$1E 

boot code 

30 

Start of code, if any 

$1FE 

The last word 

510 

U sed for checksum 

$200 


512 
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BOOT LOADER 

The boot loader resides in the boot sector and is used during system initialization to 
load an image file or a contiguous set of sectors; it is also used to load GEM from 
disk on early ST models. The format of the loader is: 


$0 

$1E 

$20 

$22 

$24 

$26 

$2A 

$2E 


boot sector 


execflg 


Id mode 


ssect 


sectcnt 


Idaddr 


fatbuf 


fname 


$39 

$3A 


(reserved) 


boot code 


0 

30 

32 

34 

36 

38 

42 

46 

57 

58 


The standard BIOS parameter block 
The word copied to cmdload flag 

If 1 mode — 0 load file, if not 0 load sectcnt sectors 

beginning at ssect 

If 1 mode <> 0 load from here 

If 1 mode <> 0 load sectcnt sectors 

Load address of file or sectors 

Address for FAT and DIR sectors 

Filename: S character name, 3 character extension 
(valid if Idmode is zero) 

Reserved 

The executable code 


Some software tools require the six bytes reserved for OEMs at offset $2 to contain 
the ASCII text 'loader 1 . 

The loader can load any file from disk regardless of where it appears in the directory 
or whether it has the form of contiguous sectors or not. 

An image file contains no header or relocation information and is an exact copy of 
the program to be executed. 
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BOOT ROM 

The initialization of the system from the boot ROM follows the predefined pattern 
of a RESET with some system variables installed and pretty color screen graphics to 
keep the operator from getting bored. 



a: 

*9 

S' 

E 

E 

E 



1 

I 

J 

mm 

J 

' 3 

J 

3 


t 



The boot di r and 2nd FAT buffer are read into memory starting at me robot* TOS IMG 
is loaded starting at $40000 and an error code produced if the file is not found. The 
memory $10000 to $20000 is used for screen buffers and should not be used initially 
for any code or data. 

The fust ST’s sold contained a small 32K boot ROM that loaded the operating 
system from disk. The boot ROM contains a small sub-set of the BIOS, just 
sufficient to read an 80 track, BPB floppy disk boot sector from either drive into 
memory and then execute it* 


Trap 13 - GEM BIOS functions implemented 


Code 

Name 

Function 

4 

rwabs 

Read/write sectors (read only) 

7 

getbpb 

Get BIOS parameter block 

Trap 14 

- extended functions implemented 

Code 

Name 

Function 

1 

ssbrk 

Reserve x bytes from top of memory 

8 

f loprd 

Read sectors from floppy disk 


All other BIOS facilities are not loaded into the system until a later stage* The first 
100 bytes of disk TOS relocate TOS. IMG at $5000 from where it takes control. 

The first TOS implementation uses the following disk parameters: 

80 track, single sided BIOS parameter block 


Bytes /sec tor 

512 

# sides/media 

1 

Sectors /cluster 

2 

# hidden sectors 

0 

Reserved sectors 

1 

Load address 

$40000 

#of FATs 

2 

FAT /directory buffer 

$8000 

# of root dir entries 

7 

Volume serial number 

0 

# of sectors on media 

720 

Media descriptor byte 

F8H 

# sectors/FAT 

5 

Filename 

TOS. IMG 

# sectors/ track 

9 
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Atari ST peripheral device 
communications 

COMMUNICATIONS OVERVIEW 

The ST supports serial and parallel communications through dedicated RS232 and 
parallel ports, and permits two further communicator! channels to be opened 
through the MIDI and DMA ports. 

The serial RS232 communication port accomodates hardware data control based on 
the PSG I/O port A, RTS and DTR outputs* and the MFP MK6890I, CTS, DCD 
and RT inputs, and Xon/Xoff software data protocol at transmit and receive baud 
rates in the range 50 to 19200 baud. The port is generally used to interface with a 
printer, modem or another computer. The MFP is located at $FFFA00 (16775680) 
and the PSG at SFF8814 (16746610). 

The general purpose parallel port interface provides bi-directional 8 bit communi- 
cations for printer operation. The port is based on the MFP MK68901 (busy 
control), the PSG I/O port A bit 5 (strobe control) and the PSG I/O port B (data 
transfer). The control is limited to a busy signal, acknowledge is not supported and 
data transfer is at a typical rate of 4000 bytes/s. 

The MIDI interface provides an asynchronous, current loop, serial data (one start 
bit, eight data bits and one stop bit) communications channel at 31.25 Kbaud, The 
MC6850 port controller may be reconfigured for most forms of RS232 interface via 
the control /status register situated at address SFFFC04 (16776196). 

The intelligent keyboard interface is also controlled by an MC6850 ACIA, but there 
is no external access provided to the port, which is of limited use other than 
accessing the ikbd command set; for reading and or writing to the clock, joysticks, 
mouse and perhaps reconfiguring the keyboard. 

The floppy disk interface is based on the Western Digital WD I772A disk controller 
and is limited to supporting two drives. 

The DMA interface is provided by an ULA device, access is through the 
control/ status configuration registers at SFF860O (16746084) et seq. 
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RS232 INTERFACE 


General 

Data is transmitted and received via an RS232 interface as a sequence of ones and 
zeroes (bits) along a three wire link, one wire being ground, one for transmitted data 
and the other for the received data. Information is sent as ‘characters* and each 
character is prefixed by a start bit (a one) and terminated with either one or two stop 
bits (zeroes). Providing the sending and receiving devices are set to the same speed 
(baud), then the stop and start bits act as a timing signal to each ‘character* sent. 
Occassionally error detection is incorporated in the form of a parity bit. If the count 
of ones in the character is even, then the eighth bit is a warning of data errors in the 
transmission. Providing the transmitting and receiving station agree on the protocol 
used* then communications will be reasonably straightforward! 

The port is reconfigured using the sequence : 

a; Save current MK68901 register contents 

b: Disable Rx and Tx enable bits 

c: Set flow control mode 

d: Set baud rate 

e; Set RS232 registers 

f: Re-enable Rx and Tx enable bits 


The extended BIOS call #$0F (15) enables selective reconfiguration of the RS232 
port according to a block of parameters pushed onto the stack; 


move .w 

sync_char P - 

(SP) 

move.w 

tx_status,- 

(SP) 

move m 

rx_status,- 

(SP) 

move.w 

usrt_cntl 

(SP) 

move.w 

flow_cntl , - 

(SP) 

move.w 

baud_rate h - 

(SP) 

move.w 

#15,-(SP) 

trap 

#14 


add . w 

#14, SP 


tst -w 

DO 


rts 




* Pushing (see chapter 3) 

# -1 

* leaves 

* parameter 

* unchanged 

* Set timer D 

* push RS232 config 

* call function 

* tidy stack, jump 7 words 

* test for error 


Data is passed through the interface using extended BDOS calls to the auxiliary 
device, the RS232 port. 
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PARALLEL PORT INTERFACE 


General 

Data is transmitted and received via a parallel port interface in blocks of 8 
(sometimes 7) data bits, set either as ones or zeroes to form a character byte. The 
character is Trained’ by a strobe signal enabling the receiving device to read the 
character transmitted, which may be printed immediately or saved in a buffer for 
subsequent printing. At some stage the printer will not be able to accept further 
input and will send a busy signal to stop the transmitter from sending additional 
data. The acknowledge signal is sometimes used to indicate that the printer is no 
longer busy, occasionally this signal line is omitted and the busy line also provides 
the 4 not busy’ signal. 

Data is passed to and from the interface using the following procedures: 

Write data : 

a: Check the busy line for high 

If line low, monitor until high 
or time out set CPU DO register to 0 

When high 

b; Set PSG I/O B port to output, use I PL 7 
c: Place data into the PSG’s B output register 
d; Switch strobe line on 

e; Switch strobe line off, set CPU DO register to -1 
Read data 

a: Set PSG I/O B port to input 
b: Switch strobe line off 
c: Check busy line for high 
loop till high 
d: Switch strobe on 

e: Get data from PSG’s B output register 

As the status register is affected, the above procedures should be performed in 
supervisor mode. 


E 


I 


St 1 


3 
3 

E ' 1 
S 


a; 

E 


3 

J 


£ ' J 

E J 

£ J 

J 

j 

J 
J 
J 
J 
J 



» 
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MIDI INTERFACE 


General 

The MIDI (musical instument digital interface) sequential circuits provide for 
integrated operation of music synthesizers, sequencers, drum boxes etc. which have 
the MIDI interface. The ST operates as a data store for a large number of 
notes/ voices which may be sent to different instruments (channels), and played 
together in sequence and time as music. The data may be ‘recorded’ from a tune 
previously played, edited and/or synthesized by entering new data in step- time-note 
format into the store for later retrieval. 

The MIDI bus provides 16 channels in one of three networking modes. OMNI, the 
default where all units are addressed together and transmit and receive on all 
channels. POLY where all the units are individually addressed and receive on one 
channel only, data assigned to non-existent channels is ignored. MONO where the 
voice of each unit is addressed seperately, providing different channels for indiv- 
idual voices within one synthesizer. 

The information transmitted is prior tised and sent as bytes, the most significant bit 
signifying either status (1) or data (0). The priority order is: 

System reset Set defaults 

System exclusive Manufacturers unique data 

Sequential circuits Roland, Yamaha etc. 

Syj zem real time Synchronization 
System common Broadcast 

Channel Note selection, program data etc. 

The MIDI port supports the optional through port which merely provides the 
MIDI in signals at the MIDI out port. 

The MIDI interface operates in RS232 current loop mode at 3L25 Kbaud. It may 
be reconfigured by resetting the control /status registers. 

The Atari ST’s extended BIOS enables the programmer to reconfigure the MIDI 
port. 
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MIDI control I status register functions (write only) 

Control/status register located at address SFFFC04 16776196 
Data register offset $2 


Control register functions (write only) 




Divide 









Bit 

select 

Bits 

Data format 

Bit 

RTS format 

Bit Interrupt 

0 

1 


12 3 4 #Bit Parity Stop 

5 6 

Tx on/off 

7 enable 

0 

0 

by 1 

0 0 

0 

7 

even 

2 

0 0 

off RTS - 

Interrupts 

0 

1 

by 16 

0 0 

1 

7 

odd 

2 

0 1 

on low 

enabled by 

| 1 

0 

by 64 

0 1 

0 

7 

even 

l 

1 0 

off RTS = 

bit 7 = 1: 




0 1 

1 

7 

odd 

1 


high 

Rx data 

1 

1 

Master 

I 0 

0 

8 

— 

2 

1 1 

off RTS = 

reg full, 



reset 

1 0 

1 

8 

— 

1 


low 

Overrun, 




1 1 

0 

8 

even 

1 

Tx break level 

DCD low to 




1 1 

1 

8 

odd 

l 

on Tx data o/p 

high step 


Status register functions (read only) 


Bit Name and Function 


0 Rx data register full 

Received data in register ready for CPU read 

1 Tx data register empty 

Transmitted data sent, load with next character to transmit 

2 Data Carrier Detect 

Indicates modem state - Carrier present 

3 Clear to Send 

Indicates modem state - Master reset - no change 

4 Frame error 

Character synchronization error 

5 Rx over-run 

Characters have been lost from stream 

6 Parity error 

Only active if parity selected 

7 Interrupt request 

Read received data register or write to transmit data register 


i i 


2-41 


ai 3 
i!T: ’ 


E 1 
5 : 

.!!! 1 
E '3 

E 3 

3 
3 
3 


* 


E 


INTELLIGENT KEYBOARD INTERFACE (IKBD) 

The intelligent keyboard functions through a MC6850 A Cl A device whose 
control/status register is located at address SFFFC00 (16776192), and functions like 
the MIDI interface. There is no external access to this port so there is little point in 
reconfiguring, but it can be used to transmit and receive data or commands from the 
keyboard, mouse, joystick and clock using the following facilities: 

Keyboard 

Return key codes 

Mouse 

Set mouse button action (keys, on press/on release) 

Set mouse position relative (default) 

Set threshold level per ‘click’ 

Set mouse position absolute 
Set scale (‘clicks’ per movement) 

Read/write mouse position 

Set mouse to simulate cursor motion codes 

Set Y origin top/bottom 

Disable/pause /resume mouse operation 

Joystick 

Enable joystick (default) 

Disable, act on request only 
Interrogate joystick 

Set mon i toring ( serial \ ine, joy st ick a nd clock) 

(serial line, button 1 and clock) 

Set key code mode (variable ‘click * 1 2 3 4 5 6 7 rate) 

Disable joystick 



Clock 

Set date and time 
Read date and time 


5 3 
E 3 
s 3 


Program control 

Load data into ikbd memory 

Read data from ikbd memory 

Execute intelligent keyboard (ikbd) program 

A status inquiry command returns a null padded 8-byte packet detailing the current 
mode and parameters of a specific function, the packet may be stored and later used 
to restore the status of the keyboard by modifying the header byte and returning the 
data as a command* 
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The keyboard scancodes do not maintain complete compatibility with IBM PC key 
scancodes. Appendix D provides the major differences due to the non-availability of 
certain keys on the ST keyboard. The additional ST keys are mapped into unused 
ctrl_ and alt_ function scancodes. 

To detect ctrl. and alt. function key combinations, execute a BDOS or BIOS 
get c ha r call followed by a BIOS kbshf t call (#$0B), 
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FLOPPY DISK INTERFACE 


The floppy disk interface is based on an on-board Western Digital WD1772A disk 
controller and that can support a maximum of two drives. 

The floppy disk read l write sequence of events is: 

a; select floppy drive 0 or 1 (PSG I/O port A) 

b; select floppy side 0 or 1 (PSG I/O port A) 

c: load DMA base address and counter register 

d: toggle read/ write to clear status (DMA mode cntrl register) 

e: select DMA read or write (DMA mode control register) 

f: select DMA sector count register (DMA mode cntrol register) 

g: load DMA sector count register (DMA mode trigger) 

ft: select FDC internal command reg (DMA mode control register) 

i: issue FDC read or write command (Disk controller register) 

j: DMA active until sector count zero (DMA status register) do not poll during 
DMA active. 

k: issue FDC force interrupt command on multi-sector transfers except at track 
boundaries (Disk control register) 

1: check DMA error status, non destructive (DMA status register) 

The DMA configuration registers are at the base address 3JFF860G (16746084) and 
the following offsets: 


4 

S4 

Disk controller data access 


6 

$6 

DMA read - mode control, write FIFO 

9 

$9 

DMA base high 

set last 

11 

m 

DMA base medium 


13 

&D 

DMA base low 

set first 


The FSG configuration registers are at base address ftFF88Q0 (16746596) and the 
following offset: 


2 S2 PSG write port 
Bit 0 floppy side 
Bit 1 floppy drive 0 
Bit 2 floppy drive 1 


There is no hardware support for sensing disk removal, therefore this facility must 
be performed in software. 
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Formatting a floppy disk 

The following procedure illustrates the technique used in formatting a floppy disk: 
Extended BIOS calls 


The standard ST format is: 



1 Sides: 1 or 2 
Sectors per track: 9 
Tracks: 80 

Ho interleave and the first two tracks zeroed (to 0 FAT 
and directory sectors, either sector bad and the media is 
' unusable)* 

/ Use disk type parameter 2 or 3 
f Serial # param, random or #$1000000 

I Execute flag usually zero, non zero if it contains loader code 
[ etc, that is to execute when the disk is booted, 

' Write boot sector (prototyped in buffer to track 0, side 0, 

1 sector 1 of the disk. 

„ Do not use rwabs calf 


The WD 1 772 'write track ? codes used to format a track are; 

Double density format : issue a 'write track* command and load 
the following values into the data register* There is a data 
request for every byte written. 


ID field 


# Bytes 
data 

60 

#$4E 

12 

#$00 

3 

#$F5 

ID 

#$FE 

Trek 

# 

Side 

# 

Sect 

# 

Len 

# 

CRC 

1 

CRC 

2 

0'$4F 0^1 T9 

# Bytes 
data 

22 

#$4E i 

12 

#$00 

3 

#$F5 

ID 

#$FB 

256 

data 

CRC 

1 

CRC 

2 

40 

#$4E 


1401 

#$4E 


i i End of 

Data field track 


Length = #512 by tes/sector (usually 2) 
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WD 1 172 DMA channel interface 

The WD1772 is interfaced through the DMA channel via the following procedure: 


To initialize the WDI772: 

iClear the fifo by toggling r/w 
;and leave in the write state. 

; Set up dma address pointer in 
:low to high order 
; SFF86QD. SFF860B S SFF8609 
irrespectively 

The following addresses are used by the WD 1772 


move . w #$1 90 , SFF86G6 
move .w #$90, SFF8606 
move . b #xx,dmalow 
(itove.b #xx.dmamid 
move.b ftxx.dmahigh 


$80 

128 

command /status register 

$82 

130 

track register 

$84 

132 

sector register 

$86 

134 

data register 


To address the WDl 772: 


move . w #$yy , &FF8606 
move.w #$zz,D7 
delay 

move . w D7,$FFBG04 

delay 

rts 


The FDC rquires two writes to 
:access the registers, the first 
; write selects the FDC register 
;aad the second write modifies 
■ the register 


To transfer from memory to floppy the values must be ORcd with #$100 and #$FF 
written to $43 E to prevent TOS from changing the value in address $FF8606* When 
the operation is complete the byte in $43E, the floppy lock variable, must 
immediately be zeroed. 


To seek to a track: 


move.w #S86 , 3FF8606 
move.w #$4F,$FF8604 
move.w #S80, SFF8606 
delay 

move.w #$17,$FF8604 


;Select the data register 
iWrite seek track ($4F last track) 
:Select command register 
;Wait for drives 
I Seek with verify. 


The FDC will generate an interrupt when the seek is finished, it can be polled at 
$FFFA01 where bit 5 is zeroed* Errors are read from $FF8604, the read clearing the 
interrupt bit* 
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To transfer data: 

mov&.b Pm , dfa ;set up dma address - clear fifo 

move.w #$190, SFF8606 

move.w #$1 , $FF8604 ;512 byte sue limit of transfer 

;write sector# (1 „ .9) 

;write track# (#$00. #327) use #$A6 
[write track# (#$28.#$4F) use #$A4 
;read track#, use #$84 

Do not use read/write multiple sector commands as they require a force interrupt 
command which is slower than re-executing a read or write. 

To format a track: 

write track# (#$00. #$27) :use #$F6 
write track# (#$28.#$4F) ;use #$F4 

Write data to the drive beginning and ending with the index pulse. 

It takes about #3 1 A00 bytes to fill a drive running at 3% . 

The existing format command produces 9 sectors of 5 12 bytes per track. 

Do not change the id -fie Id, the fourth byte is used to count the number of bytes to 
transfer, and to locate the CRC data field. It may produce incompatibilities with 
TOS if changed. The side number can be read by making a read address command 
three times without clearing the dma fifo or changing the dma pointer. 

To write an entire track : 



e 





> 


DMA INTERFACE 

There is only one direct memory access (DMA) channel which is shared by both low 
and high speed 8-bit device controllers* The configuration registers hold the 3 byte 
base address of the DMA operation which is performed through a 32-bit FIFO 
programmed by the DMA mode control register. 

The harddisk read} write sequence of events is: 

a: load DMA base address 

b: toggle read /write to dear status (DMA mode control register) 

c: select DMA read or write (DMA mode control register) 

d: select DMA sector count register (DMA mode control register) 

e: load DMA sector count register (DMA mode trigger) 

f: select HDC internal command reg (DMA mode control register) 

g: issue HDC read or write command (Disk controller register). 

1 st command AO set to 0, set to 1 for remaining commands. 

Each byte command is acknowledged with an interrupt. 

After last command byte set hard disk sector count bit 1 . 

h: DMA active until sector count zero (DMA status register) - do not poll during 
DMA active, 

i: check DMA error status, non destructive (DMA status register) 

j: check HDC status byte and if necessary perform an ECC correction following a 
verify track or read sector command. 


The entire track can be written as one long sector and then read back, without any 
error checking, using the read track command if the following format is used: 

Index pulse followed by: 

#$00 a minimum of 12 bytes for lock-on 
#$F5 3 bytes for synchronization 

The #3F5s generate $Als with a missing dock pulse to allow for alignment. 



E 

E 

E 

E 



The DMA configuration registers are at the base address 3FF8600 (16746084) and 
the following offsets: 

4($4) Disk control le r da ta acces s 

6 (36) DMA reacLmode control, write FIFO 
9 (39) DMA base high 
1 1 ($B) DMA base medium 
13 (3D) DMA base low 

The DMA registers are used to perform the floppy disk data transfers but may also 
be used for hard disk and other high speed data interfaces, bearing in mind the 
restriction of one DMA operation at a time. 

The port is used for both high speed (upto 8 Mbit/s) and low speed (250 to 500 
Kbit/s) DMA operations. 

Any modification of the DMA base address or counter register requires that they be 
set in low-mid-high order. 
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DMA bus boot code 

The following code, which is typical of the ST’s BIOS* attempts to load boot sectors 
from devices on the DMA bus. The code shows typically how the DMA bus is used 
and provides the timeout and the command characteristics expected from bootable 
DMA bus devices. 


mp 

dskctl 

fifo 

dmahigh 

dmamid 

dmalow 

flock 

dsfcbuf 

Hz_2G0 

booting 


equ 

SFFFFFAGI 

tt .B 

68901 input register 

equ 

SFFFF3604 

# .W 

controller data access 

equ 

SFFFF8606 

# .W 

DMA mode control 

equ 

S FFFF8609 

* .B 

DMA base high 

equ 

$ FFFF860B 

* B 

DMA base mid 

equ 

SFFFF860D 

* B 

DMA base low 

equ 

$43E 

* M 

DMA chip lock variable 

equ 

$4C6 

* .1 

IK disk buffer 

equ 

S4BA 

# .1 

200 Hz counter 

equ 

#$1234 

* .W 

boot checksum 


Try to boot from DMA device 


dmaboot 

moveq #0,D7 

4 # devices to try (eight) 

dmbj 

bsr 

dmaread 

11 try to read boot sector 


bne 

dmb_2 

* fai led — next device 


move 

*1 dskbuf.AO 

* disk buffer pointer in A0 


move 

,w #$OOFF,D1 

f checksum 1 00 words 


moveq #0 H DO 

* initialize checksum 

dmb_3 

add -i 

n (A0)+,D0 

# add a word 


dbra 

D1 ,dmb_3 

* until #$100 counted 


emp . w #bootfng . DO 

* Is it a boot sector 


bne 

dmb_2 

* No -- next device 


move 

. 1 dskbuf.AO 

# disk buffer pointer in AO 


jsr 

(AO) 

4 run the code. 

dmb_2 

add .1 

5 #$20, D7 

* next device 


bne 

dmb_f 

* 


rts 



Try to read DMA bus device boot 

sector 

dmaread 

lea 

fifo,A6 

* DMA control register 


lea 

dskctl ,A5 

* DMA data register 


st 

flock 

4 DMA lock against vblank 


move . 

.1 dskbuf.-(SP) 

* 


move , 

,b 3(SP) .dmalow 

4 set up DMA pointer 


move . b 2(SP) .dmamid 

# 


move . 

, b 1 (SP) .dmahigh 

* 


addq 

#4.Sp 

* 


move . 

w #5098. (A6) 

* toggle r/w, leave at read 


move . 

w #5198, (A6) 

* 


move . 

w #$098, (A6) 

* 


■ iii ■ 
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move.w #1 , (A5) 

tt write sector count reg = 1 


move.w #$088. (A6) 

4 DMA bus select {not SCR ?) 


move.b 07. DO 

* D0J to device# + command 


or.b #$08. DO 

-ft 


swap DO 

# DO . 1-xxxxxxxxDDDGlOOO 


move.w #$083 . DO 

4 xxxxxxxxOI 0001 010 


bsr webyte 

# write cmd and wait for IRQ 


bne dmr_q 

* error exit on timeout 


moveq #3,D6 

* write cmd $00 


move.l #$00008A . DO 

# cntl S8A 

dm rj p 

bsr webyte 

# four times 


bne dmr^q 

dbra Dfi.dmrjp 

* error exit on timeout 

t 


move.l #$OO0OOA , (A5) 

* write final byte 


move.w #400,01 
bsr wwait 

* 2s timeout limit 

* 


bne dmr_q 

* error exit on timeout 


move.w #$08A r (AG ) 

* select status register 


move.w (A5) , DO 

4 get DMA return code 


and.w #$ GOFF, DO 

* mask for error code only 


beq dmr_r 

* return if ok 

dmr^q 

moveq #-1 ,D0 

* set error return (-1) 

dmr_r 

move.w #$080, (A6) 

* reset DMA chip for drivr 


tst.b DO 

* test for error return 


sf flock 

rts 

* unlock DMA chip 

» 

Write ASCII command byte and wait for IRQ 

webyte 

move, 1 DO, (A5) 

4 write disk controller data 


moveq #10.01 

* wait 0.05s 

wwai t 

add. 1 Hz_2 00 , D1 

# set D1 to timeout 

wwj 

btst.b #5,gpip 

* disk finished 


beq ww_w 

* ok return 


cmp. 1 Hz„20O,D1 

* timeout yet? 


bne wwj 

* no -- try again 


moveq #-1.D1 

4 set error return (-1) 

ww_w 

rts 
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Hard disk partitioning 

Logical sector #0 contains information on the four possible hard disk partitions: 


Offset 


hd_siz 

$1C2 

pO_f lg 

31C6 

pG_id. 

S1C7 

pCLst 

JEICA 


Total size of the disk in sectors 

Non zero to show partition exists , 

bit 7 set for BIOS boot partition 

3-byte field identifier. ‘GEM' for GEMDOS 

Partition start logical sector number 


pCLsiz SICE 


Size of partition in logical sectors 
Three further optional partitions 


px_ng 

31D2 ' 

SIDE 1 

S1EA 1 


px_id 

31D3 

$1DF 

31EB 


px_st 

S1D6 

2nd $1E2 

■ 3rd 

> 4th 

px^siz 

S1DA 

$1E6 

$IF2 


bsLst 

$1F6 

Staring sector of the bad sector 

bsLcnt 

reserved 

$1FA 

$200 

Number of bad sectors 


An ST disk may contain up to four partitions, the first sector of each partition is a 
boot sector and contains a BIOS parameter block. 

The partitions are described by the 12 byte structure above. 


Root 

boot 


Partition 0 


Partition 1 


Partition 2 


Partition 3 


Optional 
bad sectr 
list 




Optional partitions 


The bad sector list is usually held at the end of the device. 
If the parameter bs Lent is zero, there are no bad sectors. 
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General 

The operating system (TOS) is a mixture of GEM and an Atari OS, both can 
completely control the system but the programmer is advised to use the GEM host 
facilities, although calls to the various types of utilities can be mixed. There are 
many reasons for using a consistent set of calls, not the least being that the 
programmer can write programs which are portable to other computers that contain 
the same operating systems. Although the writers present intention may not be to 
provide the program on an alternative computer system, it is wise to adhere 
preferably to GEM calls if possible. Those who have programs generated on older 8- 
bit machines, and now find that they cannot be used, will understand the need for 
portability* 

The BIOS and BDOS use and preserve registers in a rather haphazard manner, the 
following may be used as a guide: 

$13 BIOS calls preserve d3-d7/a3-a7 

$ 1 4 Extended BIOS calls preserve d3-d7/a3-a7 
S 1 BDOS calls use dO-d4/aG-a4 

The A-line routines provide access to the graphic primitive s; they will not produce 
portable code but will give very rapid execution of graphic functions. 
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Lastly a word of warning* GEM was developed for use on the IBM PC, and as such 
ran on the Intel 8086 processor, which stores addresses in memory low f byte first* 
Atari GEM uses the same convention in some of the tables and parameter blocks, it 
is a point programmers should be aware of, as a mixture of conventions of this kind 
is likely to cause problems. 
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Traps 


GEM BIOS CALLS 

To access the GEM BIOS functions, push the parameters in the order given onto 
the stack and then call Trap#13* Reply or status is returned in register DO and the 
data placed on the stack trashed. 

Typical use might be: 


move.w 

dr i veA F - ( sp ) 

* 

push device code 

move.w 

record. -(sp) 

# 

push record to start 

move.w 

count, ~ (sp) 

# 

push no. of sectors 

move . 1 

add rss , - (sp) 


push buffer address 

move.w 

#0. '(sp) 

> 

push read data 

move.w 

#4, - (SP) 

» 

push rwabs function call 

trap 

#13 

# 

call the function 

add w 

#14, sp 

* 

tidy the stack 

tst .w 

DO 

* 

test for error 

rts 





It is the programmers responsibility to tidy the stack after the call. The BIOS, 
accessible from user mode, is re-entrant to three levels of calls, users are advised that 
this non-standard feature should be used wisely where program portability is 
required* 
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Gem BIOS calls 


Function Parameters to push onto stack 


Notes 


pm p b . L : Poin ter to empty 



rTZ 

memory parameter MPB structure; p20 

Init vals; 


block to be 

Memory^f reej i st 


MDinBSS 


filled 

Meroory.al loc_l i st 

— ► 

0 

ez 


Roving_pointer 

— ► 

MD in BSS 


see Appendix p 

MD structure: 





Next J inkJID 


0 

* 

AID = memory 

Start_addr_b1ock 

— fr 

mbottom 

descriptor 

No_byte$_ block 


mtop-mbot 

• 


Owner.description 


0 

GETI4PB 0; Get / fi 11 a memory parameter b lock 



u 

(#$00) Trap#13 (Tidy #6) 

(No return) 




dev . W : dev code range 0 p r i nter - para 1 1 e 1 


Operations 

E: 

range 

1 auX“RS232 


0 and 4 are 


No range error 

2 con - screen 


illegal in 


checking 

3 - midi 


this mode. 

E: 


4 - keyboard 


Return DO.L 


BCONSTAT 1: return char_device input status 


#30000 none 

E: 

(#801) Trap# 13 (Tidy #4) 

#8FFFF yes (DO.L) 




dev.W: device code 0 to 3 (if dev 2, also 

ret IBM-PC compatible code 
in highword) 

BCOW I N 2: input character from device 

(#$02) Trap#! 3 (Tidy #4) (ASCII DO.W) 


WAIT for 
a character 
DO.L reply. 


char.W: character to be sent {see Appendix C Wait until 

dev. W: device code 0 to 4 for escape codes ) character 

BCONGUT 3: output character to device sent. 

(#303) Trap#13 (Tidy #6) (No return) 


E 

E 

E 

E 

E 
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Gem BIOS calls - continued 


Function 


Parameters to push onto stack 

Notes 


driv.W: 

device code 0 = floppy A 

0 ret ok 



I = floppy drive B 

neg error 



2+ = disks, networks etc. 



recn.W: 

logical sector number to start at 

rd/wr mode 


secn.W: 

number of sectors to transfer 

2 & 3 allow 


bufX: 

buffer address ( very slow if odd) 

formatter 


rwfl.W: 

rd/wT flag 0 read 

to read & write 



1 write 

and allow 



2 read do not affect 

BIOS to 



3 write media-change 

recognize 

RWABS 

4: 

rd/wr logical sectors on a device 

formatted disk 

(#$04) 

Trap# 13 

(Tidy #14) (DO.L) 

media change 


vec.L: 

vector slot address (“IL no change) 

0 to FF sys 


vecn.W; 

vector number to set/get 

toSlFF GEM 

SETEXC 

5: 

set except ion vecto r { see below ) 

to SFFFF 

(#805) 

Trap# 13 

(Tidy #8) (DO.L) 

OEMs 

TICKCAL 

6: 

return system elapsed time mS 


(#$06) 

Trap# 13 

(Tidy #2) (DO.L) 



driv.W: 

device code (0 to 2 + , as rwabs) 

Boot on $446 

GETBPB 

7: 

Get BIOS parameter block pointer 

DO.L - add. 

(#807) 

Trap# 13 

(Tidy #4) (DO.L) 

0 = not found 


dev.W; 

device code - as per bconstat 0 to 4 

0 = not ready 

BCOSTAT 

8: 

Return device character output status 

-1 = ready to 

(#8 08) 

Trap# 13 

(Tidy #4) (DO.L) 

send 


driv.W: 

device code (0 to 2 + * as per rwabs) 


MEDIACH 

9: 

Get media status 

GEMDOS 



0 - Media no change 

will try to 



1 = Media maybe changed 

read media 



2 = Media has changed 

with a status 

(#809) 

Trap#13 

(Tidy #4) (D0 + L) 

value of 1 



must be updated by installable drives 

Bits (L-31 

DFIVMAP 

10: 

Get bitmap of drives 

1 = drive in 

(#$0A) 

Trap# 13 

(Tidy #2) (DO.L) 

0 — drive out 
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Gem BIOS calls - continued 


Function 

Parameters to push onto stack 

Notes 

mode.W: 

Mode bits 

If mode “Ve 


7 

reserved (zero) 

get IBM-PC 


6 

left mouse button (insert) 

state of 

Note: Not all GEMs 

5 

right mouse button (clr/home) 

shift keys 

read bits 5 & 6 

4 

caps lock as bit vector 



3 

alt key 

in DO.L low 


2 

control key 

byte* 


1 

left shift key 

Critical 


0 

right shift key 

code for 

KBSHIFT 11: 

Set! 

keyboard shift bits 

portability 


(#$GB) Trap# 1 3 (Tidy #4) (old shift bits DO, L) 


The extended GEMDQS vectors (Appendix A) may be employed by user programs 
but should take note of the following: 

SI GO etv_ timer: Word value on stack is number of millisecs since last tick* 

Save all registers 

$101 etv-cri t i c : Stack word value is error number* save registers used. 

To ignore an error set DO.L = 0 

To retry an error set DO.L — $10000 

To abort an error set DO.L = sign extend stack parameter, 

$102 etv_term: Abort termination by a longword jump back to the top of 

the calling application or terminate via an RTS 


EXTENDED BIOS CALLS 


To access the extended BIOS functions* push the parameters in order given onto the 
stack and then call trap# 14 from user or supervisor mode. Reply or status is returned 
in register DO. 

Typical use might be: 


move . 1 
move . 1 
move.w 
move.w 
trap 
add w 
tst.w 
rts 


vector , - < sp) 

# push 

parbl k, - (sp) 

# push 

type, -(sp) 

* push 

#0, -{sp) 

* push 

#14 

* call 

#12,sp 

# tidy 

DO 

# test 


vector address 
parameter block address 
type of mouse action 
initmouse call 
the function 
the stack 
for error 
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Extended BIOS calls - continued 
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Function 

Parameters to push onto stack 

Notes 


veet.L: 

vector address (mouse interrupt handler) 

If mode = 2 


para.L: 

param 1 _y = 0 top* (Ly - 0 bottom 

then extra 

(Block 


block Mouse button command(#$07) 

word sized 

contains 

address x param thresh / s ca le / delta 

parameters 

4 bytes) 


y param thresh /scale/delta 

required in 


type.W: 

mode 0 disable mouse 

param block 



1 enable relative mouse 

xmax 



2 enable absolute mouse 

ymax 



3 unused 

xinitial 



4 enable keycode mouse 

y initial 

INITMGUS 

; 0: 

Initialize mouse packet handler 

See call 34 

(#$00) 

Trap#14 

(Tidy #12) (No return) 

re vect address 


numb.W: 

Bytes from memory top to be saved 

MUST call 

SS8RK 

1: 

Reserve block of memory at high RAM 

before OS 

flUfoi) 

Trap# 14 

(Tidy #4) (Return DO.L) 

initialized 

_PHYS BASE 2: 

Get screen base address (physical) 

At next 

(#$02) 

Trap# 14 

(T i dy #2 ) (Retu rn DO.L) 

vblank 

_LQG3ASE 3: 

Get screen logical base address now 

Used by GSX 

(#803) 

Trap# 14 

(Tidy #2) (Return D0*L) 

on screen 

J3ETREZ 

4: 

Get screen resolution 

Either 0, 1 

(#804) 

Trap#! 4 

(Tidy #2) (Return D0.W) 

or 2 


rez.W: 

Set screen resolution (0, 1 or 2) 

Negative 



cir sera, home cursor, reset VT52 

parameters 


ploc.L: 

Set screen physical location (next vblank) 

are ignored 


llocX: 

Set screen logical location (now) 

so a single 

_SETSCFiEEN 5: 

Set screen parameters 

parameter 

(#805) 

Trap# 14 

(Tidy #1 2) (No return) 

can be set 


palp.L: 

Set pallette pointer (word boundary 

At next 

_SETPALLETE 6: 

Set pallette hardware register contents 

vblank 

(#806) 

Trap# 14 

(Tidy #6) (No return) 



colr.W: 

Set colour (format- 1 6 bit color word) 

If colour 


coln.W: 

Set color number (0 to 15) 

negative 

_SETCOLOR 7: 

Set a color in hardware pallette 

ignore. 

(#807) 

Trap# 14 

(Tidy #6) 

Return old 




color (DG.W) 


I 


3-8 


Extended BIOS calls - continued 


Function 


Parameters to push onto stack 

Notes 


secn.W: 

number of sectors to be read 

Ret D0. W - 0 


sidn.W: 

side number selected 

for ok 


trkn.W: 

track number to seek to 

else failed 


stsc.W: 

sector to start reading from (lto9) 

error number 


devn.W: 

floppy device number (0 or 1) 



scrtX: 

#0j not used at present. 



buff.L: 

word aligned sized buffer address -► 

must be big 

_FLOPRD 

8: 

Read sectors from a floppy drive 

enough 

(#$08) 

Trap#l 4 

(Tidy #20) 



secn.W: 

number of sectors to write 




(< = sectors/track) 

Ret D0.W = 0 


sidn.W: 

side number selected 

for ok 


trk.nW: 

track number to seek to 

else failed 


stsc.W: 

sector to start writing to (1-9) 

error number 


devn.W: 

floppy device number (0 or I) 



scrtX: 

#0, not used at present. 

Wrking to 


buff.L; 

word aligned buffer address 

boot 1 j0 ? 0 

FLOPWR 

9: 

Write sectors to a floppy drive 

sets 'maybe 1 

(#$09) 

Trap#! 4 

(Tidy #20) 

media changed 


fcod.W: 

SE5E5 format code (not 0 or FxFx) 

Ret D0.W - 0 


magc.L: 

987654321 

for ok 


intLW: 

Sector interleave factor (say 1 ) 

else failed 


sidn.W: 

side number to format (0 or 1) 

error number 


trkn.W: 

track number to format (0 to 79) 

Buffer holds 


sptk.W; 

Number of sectors/track to format (say 9) 

0 terminatd 


devn.W: 

floppy device number (0 or 1) 

list of bad 


scrt.L: 

#0j not used at present. 

sectors. 


buff.L: 

word aligned buffer addr (8K> 9track) 

Formatting 

_FL0PFHT 

10: 

Format a floppy disk 

sets 

(#30A) 

Trap# 1 4 

(Tidy #26) 

media changed 

GETDSB 

11: 

Get device status block pointer 

Obsolete 

(#$0B) 

Trap# 14 

(Tidy #2) (Return DO. L) 

function. 


ptr.L: 

Pointer to character vector 



cnt.W: 

Number of characters to write less one. 


MIDIWS 

12: 

Write a string to midi port 


(#$0C) 

Trap# 14 

(Tidy #8) (No return) 



Extended BIOS calls - continued 


Function 


Parameters to push onto stack 

Notes 


vect.L: 

Address of interrupt routine 

Old vector 


intn.W: 

Interrupt number (0 to 1 5) 

is lost. 

_HFPI NT 

13: 

Set MFP interrupt 


(#S0D) 

Trap# 14 

(Tidy #8) 

(No return) 



devn.W: 

Serial dev 

0: RS232 

For RS232 



1 : Keyboard 


identical 



2: Midi 


o/p buffer 



L. pointer to dev buffer 

follows i/p 

Return a pointer .L 

W. size of buffer 



to a serial devices 

W. head index 


High & low 

input buffer record 

W. tail index 


w'mark start 

param block (brpb) 

( W, low-water mark 

RS232 xon 



( W. high -watermark 

xoff if 

10REC 

14: 

Get pointer to serial device i/p brpb 

flow control 

(#30E) 

Trap# 14 

(Tidy #4) 

(Return D0X) 

enabled. 


scr.W: 

Sync char reg 

68901 

-1 params 


tsr.W: 

Tx status reg 

MFP register 

do not 


rsr.W: 

Rx status reg 1 

settings 

change 


usr.W: 

Usart cntrl reg 

( Chapter 1 J 

registers 


flow.W: 

0 No flow control (default) 




1 xon/xoff (aS/aQ) 




2RTS/CTS 





3 xon/xoff &RTS/CTS 



baud.W: 

0 = 19200 

6 = 1800 

12 = 134 



1 = 9600 

7 = 1200 

13 - 110 



2 = 4800 

8 = 600 

14 = 75 



3 = 3600 

9 = 300 

15 - 50 



4 = 2400 

10 = 200 




5 = 2000 

11-150 


_RSC0NF 

15: 

Configure RS232 port 


(#80F) 

Trap#! 4 

(Tidy #14) 

(No return) 



cap IX: 

Caps lock \ 

Set pointers to 1 28 byte Ret pntr to 


shft.L: 

Shift 

Keyboard translation 

structure: 


unsh.L: 

Unshifted ) 

table. 

Unshifutable 

.KEYTBL 

16: 

Set /get keyboard 

Shift_ table 



translation table 





pointer 



(#$10) 

Trap# 14 

(Tidy #14) 

(D0X) 

Capslk_table 
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Extended BIOS calls - continued 


Function 

Parameters to push onto stack 

Notes 



Bit zero poor distribution 


..RANDOM 

17: 

Get 24- bit pseudo random number 

Bits 24-31 

(#$n) 

Trap#l 4 

(Tidy #2) (DO.L) 

are zero 


exfl.W: 

1 = boot sector executable 

retains 



0 — non -executable boot sector 

old values. 


dskt.W: 

0 = 40 track SS 




1 = 40 track DS 




2 = 80 track SS 




3 = 80 track DS 

Image is 


sernX: 

random boot serial no, if> = #$01000000 

written 


bufX: 

pointer to any 5 12-byte buffer 

to volumes 

_PR0T0B1 

18: 

Prototype a boot sector image 

boot sector 

(#812) 

Trap# 14 

(Tidy #1 4) (No return) 



secn.W: 

number of sectors to verify 




(< = sectors/track) 

Ret DO.W = 0 


sidn.W: 

side number selected 

for ok 


trkn.W: 

track number to seek to 

else failed 


stsc.W: 

sector to start reading from (lto9) 

error number 


devn.W; 

floppy device number (0 or 1 ) 



scrtX: 

#0 7 not used at present. 

Buffer holds 


buffX: 

word aligned 1024 byte buffer address 

0 terminatd 

_FL0 PVER 

19: 

Verify sectors from a floppy drive 

list of bad 

(#813) 

Trap# 14 

(Tidy #20) 

sector s.W 

SCflDMP 

20: 

Dump screen to printer 

At present 

(#814) 

Trap# 14 

(Tidy #2) (No return) 

mono only. 


rate.W: 

Rate - 1/2 cycle time-1 retains 




60/50 Hz color, old values 70 Hz monochrome 


attr.W: 

O^Hide cursor 4„Set rate 




1 _Show cursor 5_Get rate 

Returns 



2_Blink cursor 6_unused 

old rate high 



3_Noblink cursor 7_unused 

old attrib low 

CURSCON 

21: 

Set/get cursor blink 

word byte. 



rate & attributes 


(#815) 

Trap# 14 

(Tidy #6) (Return DO. W) 
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Ei =3 

■ -3 

S' S 

s a 

■ a 

■ □ 
e= g 
s= g 

E 0 

5 Li 


Extended BIOS calls - continued 

Function Parameters to push onto stack Notes 


date.L: 32-bit DOS format date and time Date Hiword 

SETT 1 ME 22: Set ikbd time and date Time Lo word 

(#$16) Trap# 14 (Tidy #6) (No return) 


GETTIME 23: Get ikbd 32-bit format date & time 

(#$17) Trap# 14 (Tidy #2) (DOX) 


Reset 

B I OS K E Y 24 : Re store power u p k cy boa rd s etting trans lation 

(#$18) Trap# 14 (Tidy #2) (No return) tables 

pn tr X : Po i n ter to charac ter s tr ing vec tor S end cm d 

nchAV: Count of characters to send -l to ikbd 

I KBDWS 25: Write a string to intelligent keyboard 

(#$19) Trap# 14 (Tidy #8) (No return) 


intn.W: MK689Q1 interrupt number 

JDISIMT 26: Disable a MK689 01 interrupt 

(#$1A) Trap# 14 (Tidy #4) (No return) 


intn-W: MK68901 interrupt number 

JENABfN 27: Enable a MK68901 interrupt 

(#$ 1 B) Trap# 1 4 (Tidy #4) (No return) 


E Li 


H ii* 
E ii 
5 y 
5 3 
5 3 



regn.W: 

PSG register number (00 to OFH) 

regn ORed 


data.B: 

Byte to write to register 

#$00 read 

GIACCES 

28: 

Read /write a sound chip register 

#$80 write 

(#8 1C) 

Trap# 14 

A tomic access only (Return DO .B) 



bitn.W: 

Bit number to be set 


OFFGIBT 

29: 

Atomically set Port A bit to zero 


(#8 ID) 

Trap# 14 

(T idy #4 ) (No return) 



b itn . W : B it n umber to be set 

QNG I B 1 1 30: Atomically set PORT A bit to one 

(#$1E) Trap# 14 (Tidy #4) (No return) 
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Extended BIOS calls - continued 


Function Parameters to push onto stack Notes 



vec.L: 

Pointer to an interrupt handler 


data.W: 

Byte placed in timer’s data register 


cntl.W: 

Timers control register setting 


timr.W: 

Timer number allocations are: 

0_A Res’d for end-users & applications 
1_B Reserved for graphics primarily 
2_C System timer (GEM etc) 

3_D RS232 baud rate and mere users 

XBTIMER 

31: 

Provide control timing facility 

(#8 IF) 

Trap#] 4 

(Tidy #12) (No return) 


ptr.L: Pointer to table of bytes (command data) 

and 0 to 1 5 load reg CM 5 with data 
and 128 load tempreg with databyte 
and 129 reg # to load using tempreg 

twos c value to add to tempreg 
terminate on tempreg value 
and 130-255 set delay data (ticks) 
DOS0UND 32: Produce a sound (Appendix L) 

(#$20) Trap# 14 (Tidy #6) 


Usually in 
twos except 
129 which 
is in sets 
of 4 bytes. 


stop 


conf.W: Bit 0 0 = dot matrix, I = daisy wheel 

10 = colour dev* I = monochrome 

2 0 = Atari prnt, 1 - Epson prntr 

3 0- draft, 1 = final 

4 0 = parallel, 1 = RS232 port 

5 0 = formfeed, 1 = single sht 

6-14 reserved 

1 5 must be zero 

SETPRT 33: Get/set printer configuration byte 

(#*21) Trap# 14 (Tidy #4) (DQ.W) 


-1 returns 
configuration 
byte else 
change and 
return the 
old value. 
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Extended BIOS calls - continued 


Function 

Parameters to push onto stack 

Notes 

Structure 

MIDI_input 

(BIOS buffer 



longword 

routine) 


DO. B char 

format 


keybrd_err 

Called when over- 


68901 



MIDI_err 

run detected 


or 6850s 


ikbd.stat Pointer to packet 
mouse_pack handlers (pointer to 





clock„pack packet received in 



(mouse vect 


joy st_p ack A0 & on stack. L) 



used by 


MIDI_vec Call when character 



GEM & GSX.) 


ikbd_vec available on 6850 


Return by 

KBDVBAS 

34: 

Return pointer to structure base 

RTS and 

(#S22) 

Trap# 14 

(Tidy #2) 

(D0.L) 

within 1ms 


rept.W: 

Rate of key- re peats (System ticks) 

-1 params 


init.W: 

Delay before key-repeat starts 

no change. 

KBRATE 

35: 

Get/set keyboard repeat rate 

Ink hibyte 

(#823) 

Trap# 14 

(Tidy #6) 

(DO.W) 

rept iobyte 

_PRTBLK 

36: 





(#824) 

Trap# 14 

(Tidy #2) 




VSYNC 

37: 

Wait till next vblank and return 

Graphics 

(#825) 

Trap# 14 

(Tidy #2) 

(No return) 

synchronize 


Code.L: 

Pointer to code that ends with RTS 





(Hackers’ access to hardware & 

Must not 



protected locations 


call BIOS 

SUPERX 

38: 

Exec code in supervisor mode 

or GEMDOS 

(#826) 

Trap# 14 

(Tidy #2) 


functions 

PNTAES 

39: 

If AES not present then return, else reboot 


(#827) 

Trap# 14 

(Tidy #2) 






i: 
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GEM BDOS FUNCTION CALLS 

To access GEM BDOS functions, push the parameters in the order given onto the 
current stack and then call trap#! . Any byte, word or longword reply or the address 
of a parameter block will be returned in register DO. 


move.W driveB.-(SP) 
move.W #13.- (SP) 
trap #1 

adcLW #4, SP 

rts 


* push drive number (2) 

* push setdrv function call 

* call the function 

* tidy stack 

* return with bitmap in DO 


It is the programmer's responsibility to maintain the stack integrity after the call. 


Function 

Parameters to push onto stack 

Notes 

P_TERM_0LD 

(#800) Trap#l 

0: End process and return to parent, 

(Tidy #2) 

Return code 
zero 


G_C0N IN ] ; Read character from standard i/p & echo 

(#$01) Trap#l (Tidy #2) (Return DOX) 


es 

E: 

E 

E 

m 

i 

E 

E 


The console 
scan code is 

low byte of the 
high word. 
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Gem BDOS calls - continued 


Function Parameters to push onto stack Notes 


C_NECIM S: Read a character from standard input No echo* aC, 

(#$08) Trap#l (Tidy #2) (No return) aQ & a S act 


addrX: Address of null terminated string Char bytes 

C_CGNWS 9; Write string to standard output terminated 

(#809) Trap#l (Tidy #6) (No return) by a zero. 


addr . L : Addres s of inp ut b u f fer On retu m , 

(First byte data portion length) 2nd len read 

C_C0NRS 10; Read edited string from standard input 3-n chars 

(#$QA) Trap#l (Tidy#6) (Buffer returns) n + lzero 


C_C0N IS 1 1 : Check status of standard input character ready 

(#$0B) Trap#l (Tidy #2) (DOX) -t_Yes, 0_No 


driv.W: Drive number: 0 = A, 1 = B * , 15 = P Return bitmap 

D_SETDRV 14: Set default drive of drives 

(#8QE) Trap#l (Tidy #4) (DO.L) present 


C_C 0 N 0 S 16: Check statu s of s tanda rd o utput - i ready to 

(#810) Trap#l (Tidy #2) (DO.L) Rx,0 = not 


C_ P R N 0 5 17: Check statu s of s tanda rd p r i nt d e v ice - 1 ready to 

(##H) Trap#! (Tidy #2) (DO.L) print, 0 = not 


C_AUXIS 18: Check status of standard aux device i/p -I char rx 

(#812) Trap#l (Tidy #2) (BOX) 0 = no chars 


C_AUX0S 19: Check status of standard aux device o/p -1 ready to 

(#813) Trap#! (Tidy #2) (DOX) Rx.0 = not 


CJ3ETDRV 25: Get current drive drive A = 0 

(#819) Trap#l (Tidy #2) (D0X) B = letc* 


addr.L: Disk transfer address Address 

F^SETDTA 26: Set d i sk t rans fer ad d re ss used by 

(#8 1 A) Trap#! (Tidy #6) (No return) f_sflrst(78) 


T_G E I D A T E 42 : Get date (as se t da te fo rmat ) Date ret u rn 

(#82 A) T rap# 1 (Tidy #2) (D0X) in low word 


Gem BDOS calls - continued 


Function Parameters to push onto stack 


Notes 


date.W: Date format date; bits CM, 1 to 31 Error refd 

T_$ETDATE 43: Set date: month: bits 5-8, 1 to 12 if date not 

(#$2B) Trap#l (Tidy #4) year: bits 9-15, 1980-2100 valid 


T_GETT I ME 44: Get time (as set time format) Time return 

(#82C) Trap#l (Tidy #2) (DOX) in iow word 


time.W: Time 

format secs: bits 0-4, step 2s Error ret 

T_SETTIME 45: Set date: mins: bits 5-10 if date not 

(#$2D) Trap#l (Tidy #4) hour: bits 1 1-15 (D0.L) valid 


FJ3ETDTA 47: Get disk transfer address 

(#82F) Trap#l (Tidy #2) (DOX) 


S J/E R3 1 ON 48 : Get version no. ( 1 .00 lo-hi byte) 000 1 H for 

(#$30) Trap#l (Tidy #2) (D0.W) 1st release 


exit.W: Exit code (process return code) total size 

of program, base page 3 text , bss etc 
keep.L: # bytes to keep in process description 

P^TERMRES 49: Terminate and stay resident 
(#$31) Trap#l (Tidy #8) (No return) 


May cause 
problems 
for future 
conversions 


OR EE 


(#836) Trap#! 


driv.W: Drive number: 0 = current, I = A, 2 = B 

info.L: Address of drive info buffer 

54: Get drive free space (data in buffer 

4 x longwords) 

(Tidy #8) (No return) 


Buffer pb.L 
# free dust 
#clust-total 
#bytes/sect 
#sect/clust 


path.L: Address of string containing pathname 

D„CREATE 57: Create a subdirectory 

(#$39) Trap#l (Tidy #6) (DOX) 


pathX : Address of string containing pathname 

D_DELETE 58: Delete a subdirectory 

(#83A) Trap#l (Tidy #6) (DOX) 


path X: Address of string containing pathname 

CLSETPAT 59; Set current directory 

(#83B) Trap#! (Tidy #6) (DOX) 


Pathname is 
terminated 
in a null. 

0 ret ok 
neg error 
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Gem BDOS calls - continued 


Fit net ion Pe tame te rs to p ush onto stack 

Notes 

attr.W: File attributes: #801 read only 

#802 hidden file, #$04 hidden system file 
#808 File, vol label in 1st 1 1 bytes 
pathX: Address of string containing pathname 

F_C REATE 60: Create a file 

(#83 C) Trap#l (Tidy #8) (D0.L) 

Ret file 
handle if 
ok. Neg if 
error. 
Pathname 
ends in 0 

attr. W: File read-write mode 

0 = file open for read only 

1 = file open for write only 

2 = file open read and write 

path X : A ddr ess of s or i n g con ta i n i ng pathn ame 

Ret file 
handle if 
ok. Neg if 

error. 

F_QPEN 61: Openfile 

(#$3D) Trap#! (Tidy #8) (D0.L) 

Pathname 
ends in 0 

hndl.W : File handle (errors may crash system) 

F_CL0SE 62: Close file 

(#83E) Trap#l (Tidy #4) (D0X) 

0 ret ok 
neg error. 

buffX: Address of buffer to store bytes 

bytsX; Number of bytes to read 
hndl.W; File handle (errors may crash system) 
F_READ 63: Read file 

(#$3F) Trap#l (Tidy #12) (D0.L) 

DO contains 
no. bytes 
read. 

Negative on 
error. 

buff.L: Address of buffer storing bytes 

byts.L: Number of bytes to write 

hndl.W; File handle (errors may crash system) 
F_WRITE 64; Write file 

(#840) Trap#l (Tidy #12) (D0.L) 

DO contains 
no. bytes 
written. 
Negative on 
error. 

path.L; Address of string containing pathname 
FJELETE 65: Delete file 

(#841) Trap#l (Tidy #6) (D0.L) 

0 ret ok 
neg error. 

fmod, W: 0: move n bytes from beginning 

1 : move n bytes from current posn 
2: move n bytes from end of file 
hndl.W: File handle 

Pos moves 
to end of 
file, neg 
beginning 

nbytX: Signed number of bytes argument 

F_SEEK 66: Seek file pointer 

(#842) Trap#l (Tidy #10) (D0X) 

D0= Abs. file 
pointer loc. 
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Gem BDOS calls - continued 


Function Parameters to push onto stack 

Notes 

attr.W: File attributes: #$01 read only 

$02 hidden file, #$04 hidden system file* 
$08 File* volume label in 1st 1 1 bytes, 
$10 File is a subdirectory, 

$20 File has been written & closed* 
wrt.W: 0_get/l„set file attributes 

path.L: Address of string containing pathname 

F_ ATT RIB 67 : Get / set fi le at tr ibu te s 

Ret file 
handle if 
ok. Neg if 
error 

Pathname is 
terminated 
in a null* 

(#843) Trap#l (Tidy #10) (DO.L) 

Get in DO.L 

shnd.W; . Standard file handle to duplicate 
F_DUP 69: Duplicate file handle 

(#$45) Trap#! (Tidy #4) (DOX) 

Error ret 

shnd.W: Standard file handle to force/0 con i/p 

nhnd . w : N on^s tand a rd fi le h andle 

F_Force 70: Force point file handle to non- 

standard handle file or device 

(#$46) Trap#l (Tidy #6) (DOX) 

-1 con o/p 
“2 serial 
-3 parallel 

driv.W; Drive number: 0 = default* I = A. + . etc. 
path X: Address of 64 byte buffer for pathname 

D_G ETPATH 7 1 : Get current directory 

(#$47) Trap#l (Tidy #8) (DOX) 

Buffer min 
64 bytes. 


allocated block may not be on a word boundary 
nbyt.L: Bytes to allocate or-1 ret max available DOX = 0 if 


M_MAL LOG 72 : Allocate memory (DO.L start pointer) 

o r Read free m emory (DOX bytes a va i lab I e) 
(#$48) Trap#l (Tidy #6) (DO.L) 

alloc fails 
or pointer 
to block. 

f ra d * L : Add re ss of memory to free 

M_FREE 73: Free al loca ted memory 

(#$49) Trap#! (Tidy #6) (DO.L) 

0 ret ok 
neg error 

rmemX; Length of retained memory 
mmemX: Start of memory space to modify 

zero.W: zero 

H_SHR IMK 74 : Shrink size o f al loca ted memo ry 

(#$4A) Trap#l (Tidy #12) (No return) 

Reallocates 
unused mem. 
for GEMDOS. 
0 ret ok 
neg error 
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Gem BDOS calls - continued 

Function Parameters to push onto stack 

penvX: Pointer to environ string* 0 for parent 

pcmd.L: Pointer to command tail incl redirection 

pa th . L : Add res s of string con taining p athn ame 

mode.W: 0 = load & exececute ret term child code 

3 = load only. ret. DO.L base page add. 

4 — create basepage, 5 = execute only 

75 : Load or execute a process 

Trap#l (Tidy #16) (DQ.L) 

set return code positive to avoid confusion 
with negative system error codes 
$tat*W: Interrogation code for parent 

P_TERH 76: Terminate process* control to parent 

(#$4C) T rap# 1 (Tidy #4) (DO.L) 


P__EXEC 

(#S4B) 


F_S FIRST 
(#ME) 


satt.W: Search attributes 

$00 normal files* #S01 read only 
$02 hidden files* #$04 hidden system file 
$08 volume label file* #$10 subdir files 
$20 File has been written & closed 
path.L: Address of string containing pathname 

78 : Search for 1 st occurence Filespec 

44 “by te DT A buffer created if found 
0-20 o/s reserved 21 file attributes 

22-23 Time stamp 2L“25 Date stamp 

26-29 Filesize.L 30-43 Name.ext 


(#$4E) Trap#l (Tidy #8) (DO.L) 


79 : S earch for nex t occu rence fi lesp ec 

(Uses 1st 20 bytes of DTA buffer * 
F_SNEXT name* ext updated on success) 

(#S4F) Trap#l (Tidy #2) (DO.L) 


F_, RENAME 


pth2.L: Pointer to l new' file string 

pthLL: Pointer to ‘old’ file string 

zero.W: zero 

86: Rename a file 


(#$56) Trap#l (Tidy #12) 


(DO.L) 


Notes 

Mode 3 is 
used for 
overlays* 


Ret DOX 
error if 
load fails. 


0 ret ok 
non-0 error 


Filename 
may include 

<*' or *r 

wildcards. 

If file not 
found ret 
EFILNF code 
in DOX 


1st 20 bytes 
DTA buffer 
must not be 
altered. 


Rename a 
file 


Gem BOOS calls - continued 


Function Parameters to push onto stack Notes 


i nfo . W : G_s et / 1 _get date and time 

hndl.W; File handle 
buff.L: Time and date buffer pointer 

F J)AT I ME 87: Get/set file date and time stamp 

Buffer first word 
Bit format: 

days 0-4, 1 to 31 
month 5-8, 1 to 12 
year 9-15, 1980 to 2100 
Buffer second word 
Bit format: 

secs 0-4 in 2 second steps 
mins 5-10 
hour 1 1-15 


C#$5 7) Trap#l (Tidy #10) (No return) 


DTA buffer 

Offset 



800 

0 


OS reserved 



$15 

21 

Byte 

file attributes 

$16 

22 

Word 

file time stamp 

318 

24 

Word 

file date stamp 

81A 

26 

Longword 

longword file size 

81E 

30 

7 words 

H 

name and ext of file found 


Use function #$1A (dec 26) to set DTA buffer address and function #$2F (dec 
47) to get DTA address. 
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Supervisor! User toggle 

This special function allows users to get in and out of supervisor mode from GEM 
DOS. 


Function 

Parameters to push onto stack 

Notes 


stdc.L: -l_getmode: Return 0_user 

(D0.L) ^supervisor 

<>—l switch mode 

Return 


a) User to supervisor mode 

value of 


0_set supervisor stack equal 

old super 


to user stack before call 

stack in 


<>Q_set supervisor stack equal 

DOX 


to stckX 

b) Supervisor to user mode 

The old 


set supervisor stack from 

value of 


stckX which must be first 

super stack 


SMODE function call or the 

MUST be 


system will crash. 

restored on 

SMODE 

32: Set / get sup er v i sor/ user mode 

process 

(#$20) 

Trap#! (Tidy #6) (DOX) 

termination 


Test for mode 

novel #S1,-(sp) * Returns DOT 

move . W #32,‘{sp) * SO = user mode 

trap #1 * SFF - supervisor mode 

addq #6 r sp 4 

User to supervisor mode 

clrT -(sp) 

move.W #32 f -(sp) 

trap #1 

addq #6 . sp 

move.L 00,save,stk 


Supervisor to user mode 

move.L save_stk r - (sp) * Recover old supervisor stack 
move.w #32 T -{sp) 

trap #1 
addq #6,sp 


Set supervisor stack equal to 
user stack before this call, 


Save old supervisor stack, value 


and back, into user mode. 
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EXTENDED BDOS FUNCITON CALLS 

To access the extended BDOS functions, the DO.W register is loaded with the 
function code, an address pointer is placed in DI (.L) and trap §2 called. A return if 
any, is placed in DO, W. * JI 

GEM VDT and AES may be accessed by loading the relevant parameter block 
a ress into d 1 , the function number into dO and making an extended BDOS call* 

GEM VDI 

tfove.l #contrl, pblock 
move.l tfpblock , di 
move.w 73 P dO 
trap #2 

and GEM AES 

move, 1 ^control r _c 
move! 

move.w #$cB , dO 
trap #2 


* address of VDI param block 

* set dO equal to 115 and 

* execute an extended BDOS call 


* address of AES param block 

* set dO equal to 200 and 

* execute an extended BDOS call 


Code# Hex Dec Function Notes 


DO.W: #$00 

RESET ; 

Trap #2: 


Terminate current program and 


DLL: #pblock 

DOW: #$73 115 

Trap #2: 

DLL: #control 
DO.W : #$C8 200 
Trap #2: 

DO.W: #$C9 201 


return to CCP level 
VDI param block pointer 
VDI function number 
GEM VDI access 
AES param block pointer 
AES function number 
GEM AES access 


The function 
does not return 
to calling program 


The trap #2 reset call simply calls the GEMDOS trap#l process terminate 
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GEM VDI function calls 

The VDI functions are accessed through an extended BDOS call and the VDI 
parameter block (five long word pointers to the word tables; cntrl, input attribute 
and points, output attribute and points). The parameter and array blocks, which are 
usually initialized by an AES call to APPLfNIT . have the following formats: 

VDI parameter block 


Offset 


DO 

$ 0 

Control 
table pointer 


$ 4 

I/P attribute 
table pointer 

intin 

$ 8 

I/P points 
table pointer 

ptsin 

8 C 

O/P attribute 
table pointer 

intout 

$10 

O/P points 
table pointer 

ptsout 

$14 




Control table 

Offset 


$0 

$2 

$4 

$6 

$8 

$a 

sc 

(*E-0 


Opcode 

Length of input 
coordinate table 

Length of output 
coordinate table 

i ^ 

Length of input 
attribute table 

p 

Length of output 

attribute table 

V 

Subfunction 
ident number 

Device handle 

Opcode dependant 
information 


Length in 
word pairs 


Length in 
words 


zero if 
can't be 
opened 
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Attribute table 

intin Typical 



Offset 


Points table 


ptsin 

Typical 


ptSQUt 

usage 


SO 


x coordinate 

| word 

$2 


y coordinate 

| pair 

$4 




$6 




S8 


width 

1 word 

SA 


height 

J pair 

Offset 




Not all the GEM VD1 function calls have been implemented on the Atari ST* but 
they are listed in this section. It might help a little in translating programs to the ST 
that use these function calls, A minimum application stack space of 128 bytes is 
required, plus space for the GEM arrays. The VDI function calls have been detailed 
in groups as follows: 

Workstation control functions: 

Define the workstation parameters and defaults; these govern the font and the 
window size to be used and the generation of virtual screens. 

Output functions; 

These functions draw the graphic primitive on the specified output device. 

General drawing primitive functions: 

Define the basic graphic primitives of line, arc, filled and unfilled ellipse and 
rectangle, and of justified text. 

Attribute functions: 

Define the output style of the graphic primitives; the line, marker, text cell and 
polygon for colour, size and fill. 
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Raster operations: 

Provide the ability to transpose a source block of pixels to a destination location 
on the basis of a logical operation between the bits comprising the source and 
destination. 

Input functions: 

Enable the programmer to provide the user with both a bequest and wait on 
event’ and a bequest, sample and return’ mode of inquiry. 

Inquire functions: 

Return the status or attributes of a specific device 

Escape functions: 

Enable the application to access special features applicable to certain graphic 
devices. 


VDI Parameter block sizes 

The numbers of parameters required by the various functions arc detailed in the 
tabular format: 

Control table 


Pointpair Integers Dev . 

Function Op in out in out GDP name Comments 

SO $2 $4 $6 $8 $A SC 


The table contains details of the parameter input and output word sizes; note that 
the points value is half the table size (a point is defined by a pair of x and y word- 
sized coordinates - a longword). 

OPEN WORKSTATION FUNCTION v.opnwk 

The major VDI function in terms of size is the "open workstation function*, which 
sets up a named screen (device handle); the desktop window' is identified as device 
name zero. The new screen is initialized to graphics mode, cleared and the 
parameter table outputs initialized. The v_opnwk (op„i) function is not available 
on the Atari ST, programmers should use the virtual workstation function v„opnvwk 
(op _ 100). 
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The control table 


Control Array 

offset Data size B Function 


so 

0 

1 


Opcode for -open workstation 


S2 

2 

0 

0 

# of input point pairs 

ptsin 

84 

4 

6 

24 

# of output point pairs 

ptsout 

S 6 

6 

11 

22 

Len of input attribute table 

intin 

88 

8 

45 

90 

Len of output attribute table 

intout 

SA 

10 

— 


Not used 


SC 

12 

X 


Handle for this device 

(out) 


Attribute input table (intin) 


Intin 

Offset 

Initial defaults (style, colour etc.) 

code 

VDI Op 
no 

8 0 

0 

Device driver 

(screen = 1 ) 


8 2 

2 

Linetype 

(solid = 1 ) 

15 

3 4 

4 

Polyline colour index 


— 

8 6 

6 

Marker type 

(dot = 1 ) 

18 

S 8 

8 

Polymarker colour index 


18 

$ A 

10 

Text face 


21 

8 C 

12 

Text colour index 


— 

8 E 

14 

Fill interior style 


23 

810 

16 

Fill style index 


24 

812 

18 

Fill colour index 


— 

814 

20 

NDC to RDC transform flag (2 only) 



0 map full NDC to full RC 

1 reserved 2 Use RC coords 


The input ranges required to open a workstation with a specific attribute can be 
found, in the table box for that attribute, later in this chapter. 

The procedure names are limited to the maximum of eight unique characters 
supported by the Atari ST 4 C’ compiler. Note that S C external names are prefixed 
by an { J (underscore) which reduces the uniqueness to seven characters. 
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&' 


m 


■ 
m 
e 


: 
i 

.3 
3 
3 
3 

fc 3 

£ 3 

: ' d 


l 


fc □ 
5= □ 
6= 3 

e a 


Attribute output table (intout) 


In tout Default output parameters Typical b&w 

Offset values 


$ 0 

0 

Max pixel width 0 to 639 I mono 

S27f 


639 

8 2 

2 

Max pixel height 0 to 399 ' values 

S18f 


399 

8 4 

4 

Dev coord flag (0 = fine, I - coarse) 


0 


8 6 

6 

Pixel height, microns 




372 

8 8 

8 

Pixel width, microns 




372 

8 A 

10 

No. char heights (0 = continuous) 


3 


8 C 

12 

No. line types 



7 


8 E 

14 

No. line widths (0 = continuous) 


0 


810 

16 

No. marker types 



6 


812 

18 

No, marker sizes (0 = continuous) 


8 


$14 

20 

No, faces supported 



1 


816 

22 

No. patterns 


318 


24 

818 

24 

No. hatch styles 


$c 


12 

81A 

26 

No. simultaneous colours (2 = mono) 


2 


SIC 

28 

No. generalized drawing primitives 

8 a 


10 



List of 1st 10 GDP’s ( 

-1 ends list) 




8 IE-830 


1 — Bar 6 = 

Elliptical arc 






2 = Arc 7 = 

Elliptical pie 


1 to 10 


30-48 

3 — Pie slice 8 — 

Rounded rectangle 






4 = Circle 9 — 

Filled 8 above 


3 0 3 




5 = Ellipse 10= 

Justified graphic text 

3 3 0 




Attrib list for GDP’s 



3 0 3 


$32-$44 


0 = Polyline 



2 


50-68 

1 — Polymarker 3 = 

Fill area 

respectively 



2 — Text 4 — 

None 




846 

70 

Colour 

0 = no, 1 = yes 


0 


848 

72 

Text rotation 

Capability 


1 


84A 

74 

Fill area 

flags 


1 


84 C 

76 

Cell array operation 



0 


84E 

78 

No. colours (2 = mono , >2 = no. colours) 


2 


850 

80 

No. locator devices 

1 = keyboard only 


2 





2 — keyboard + i/p 



852 

82 

No. valuator devices 

1 = keyboard 


1 


854 

84 

No. choice devices 

1 “ function keys 







2 = button device 


1 


856 

86 

No. string devices 

1 - keyboard 


1 


858 

88 

Workstation type 



2 




0 = o/p only 







1 = i/p only 3 - 

reserved 






2 = inpu t / output 4 - 

metafile output 
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Output points table (ptsout) 


PtSOUt 

Output points table 

Typical b & 

w 

Offset 



values 


S 0 

0 

Min character width 


5 


S 2 

2 

Min character height 


4 


S 4 

4 

Max character width 


7 


$ 6 

6 

Max character height 

$d 


13 

8 8 

8 

Min line width 


1 


8 A 

10 

Zero 


0 


8 C 

12 

Max line width 

828 


40 

8 E 

14 

Zero 


0 


810 

16 

Min marker width 

8f 


15 

812 

18 

Min marker height 

8b 


11 

814 

20 

Max marker width 

$78 


120 

$16 

22 

Max marker height 

$58 


88 


WORKSTATION CONTROL FUNCTIONS 

The following functions set the workstation parameters and defaults for use by the 
application: 




Point pair Integers 

Device 


Function 

Op 

in 

out in out GDP 

name 

Comments 


so 

$2 

$4 S6 $8 SA 

SC 


Close 

2 

0 

0 0 0 

— - 

Ret to alpha mode. 

workstation 





Close device and 

v_dswk * 





flush buffers. 

Open 

100 

0 

6 11 45 

i/p sern Permits multiple 

virtual 



parameters 


windows based on 

screen 



as opcode 1 

o/p new one screen with 

v_opnvwk 




window different 





o, error 

attributes. 

Close 

101 

0 

0 0 0 

. — 

Close virtual 

virtual 





screens first. 

screen 





Stop further 

v_e1svwk 





output to screen. 

Clear 

3 

0 

0 0 0 

— . 

Clear the screen. 

workstation 





New page if poss. 

v“_c 1 rw k 





Dd buffer data. 

Update 

4 

0 

0 0 0 

— 

Execute graphic 

workstation 





commands waiting. 
No screen effect. 

v_updwk 





Use to print data. 

Load 

119 

0 

0 1 1 

— 

Load additional 

font 



intin(0) = 0j reserved 


fonts. 



intout(0) = # fonts loaded 


intin(0) reserved 

vst-loacLfonts 


may not be implemented 


for future use. 

Unload 

120 

0 

0 1 0 

— 

Unload font from 

font 



intin(0) = 0, reserved 


mem if no other 
live users. 

vst_un loadLfonts 


may not be implemented 


intin(0) reserved. 

Set 

129 

2 

0 1 0 

— 

Disable/enable 

dipping 

a ,b — 

1 

, intin(0) 


clipping of 

rectangle 

1 


= 0_off (default) 

output primitive. 

vs-clip 

1 

_ c 

t d <>0_on 


ptsin a,b,c 3 d 





* Not available on the Atari ST, programmers should use v_clsvwk (op_lGl) 
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OUTPUT FUNCTIONS 

The following functions draw the graphic primitives (lines* arc etc.) on the current 
device using the current attributes. 


Output functions 



Point pair Integers Device 


Function 

Op in out in 

out GDP name 

Comments 


$0 S2 $4 $6 

S8 SA SC 


Polyline 

6 n 0 0 

0 — 

Line join 

v_pl i ne 

minimum 2 coordinate pairs 

n pairs of points. 

Poly, 

7 n 0 0 

0 — 

Draw marker at 

marker 



each of n pairs 

v„pmarker 



of points. 

Text 

8 1 0 n 

0 — 

Write char string 


intin(O) = text string 

(Strg ien) 

to device, 0-255 


ptsin(0) = x coot 

Text start 

I min word LSB 

v_gtext 

(2) = y coot 

position 

contains char. 

Filled 

9 n 0 0 

0 — 

Outline if device 

area 

n ^ x,y 


can’t fill. Close 

v„fi 1 1 area 

points 


area if open. 

Fill 

114 2 0 0 

0 — 

Rectangular area 

rectangle 

| ptssn(O) = h 
( 2) = b 

ptsin(4)=c 
(6) = d 

fill. 

vr_recfl 

1 c,d 


ptsin a* b, c, d 

Cell 

10 2 0 n 

0 — 

Draw rectangular 

array 

reel. . — c,d 

length 

cell array. 

array | | of colour 

ptsin a,b,c ? d 



based on color 

Row length Xc Cntrl $E 

Colour Xc — r 

cells Xc x Yc 

$ W or ds / row Cnt r 1 $10 

index 


$ Rows Xc 

Cntrl S12 

array * Vc 

Writing mode Cntrl $ 1 4 



v_cel 1 array 




Contour 

103 i 0 I 

0 — 

Flood fill area 

Ell 

intin(O) — color index 


bound by edge or 


ptsin(O) = x coor 

1 Starting 

colour. 

v_contour 

ptsin(2) = y coor 

point 
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GENERAL DRAWING PRIMITIVE FUNCTIONS (GDP’s) 
The-GDP’s provide the basic graphic primitives of line, arc, ellipse etc. 


Function 

Point pair Integers Device 

Op in out in out GDP name Comments 

SO $2 S4 $6 $8 SA SC 

GDP 

(General 

format) 

11 n — — — x 

Bar 

11 2 0 0 0 1 — Area attributes 

v_bar 

ptsin(0) - corner x coordinate 
(2) = comer y coordinate 
(4) = diag opp x coor 
(6) = diag opp y coor 

Arc 

11 4 0 2 0 2 — Line attributes 

v-_arc 

ptsin(0) = centre x coordinate 
(2) = centre y coordinate 

(4) = 0 ptsin(A) = 0 imin(0) - start angle 1 Oto 

(6)-0 (C) = radius (2) — end angle J 3600 

(8) = 0 (E) = 0 

Pie 

v„pi es 1 \ ce 

11402 0 3 — Area attributes 

Parameters as for arc above 

Circle 

11 3 0 0 0 4 — Area attributes 

v_cirele 

ptsin(0) = centre x coordinate ptsin(6) - 0 

(2) = centre x coordinate (8) - radius 

(4) — 0 (A) = 0 

Ellipse 

11 2 0 0 0 5 — Area attributes 

ptsin(0) = centre x coordinate 
(2) = centre y coordinate 
(4) = radius x axis 

v_el 1 ipse 

(6) = radius y axis 

Elliptic 

arc 

11 2 0 2 0 6 — Line attributes 

ptsin(0) - centre x coordinate intin(0) = start angle 1 0 to 

(2) = centre y coordinate (2) = end angle J 3600 

(4) = radius x axis 

v_el 1 arc 

(6) = radius y axis 
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(general drawing primitive functions — continued 


■ 

Point pair Integers 

Device 


Function 

Op in out in out GDP 

name 

Comments 


SO S2 S4 $6 S8 SA 

SC 


GDP 

11 n — — — x 

— 


(General format) 



Elliptic pie 

11 2 0 2 0 7 

— 

Area attributes 

v_e 1 1 p i e 

Parameters as for elliptic arc above 



Rounded 

11 2 0 0 0 8 

— 

Line attributes 

rectangle 

ptsin(0) = corner x coordinate 




(2) = comer y coordinate 




(4) = diagonally opposite x coordinate 


v_rbox 

(6) = diagonally opposite y coordinate 


Filled 

11 2 0 0 0 9 

— 

Area attributes 

rounded 




rectangle 

Parameters as for rounded rectangle 


v_rfbo* 




Justified 

11 2 0 2 + n 0 10 

— 

Text attributes 

graphics 

ptsin(0) = x alignment intin(0) - interword space flag 

text 

(2) = y alignment (2) = interchar space flag 


(4) = string length 

0 = don’t mod space 


(6)= zero W s 

= 1st char 

1 Null terminated 


(4 + 2n) 

= Last char J string 

v_justified 

Intin uses least significant byte for character 



Notation used for 
a ngu lar sp cci fi cations ; 


1800 


.900 


*.0 


2700 
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ATTRIBUTE FUNCTIONS 

The attribute functions determine the output style of all the graphic primitives; that 
is colour, line style, character size etc. 



Function 

Pain (pair Integers 

Op in out in out 

SO S2 S4 $6 S8 

Device 
GDP name 

SA SC 

Comments 

Set 

32 0 0 1 1 * 

— 

Out of range uses 

writing 



replace mode. 

mode 

intin(0)= 1 Replace 


Modes 2, 3 and 4 


= 2 , t ra ns paren t(m as k 1 s) 

based on line or 


— 3,XOR 


fill pattern mask 

vswr„mode 

= 4, reverse transparent (mask 0s) 


Set a 

14 0 0 4 0 

- — 

Redefine a colour 

colour 





intin(0) = colour index 

In mono 

No action if a 


(2) — red J colour 

any colour 

lookup table is 


(4) = green > intensity 

is set to 

not available or 

vs_color 

(6) = blue J 0 to 1000 

white • 

'out of range’. 

Set 

15 0 0 1 1 * 

— 

All devices 

polyline 



support at least 

line type 

intin(0) = line style 


six line styles. 


1 - solid, 5 = dash, 




2 = 1 ong da sh , 6 = das h-do t-dot , 

User defined 


3 = dot, 7 = user defined . 

defaults to solid 

vsl_type 

4 = dash-dot, (see below } 

until defined* 

Set user 

113 0 0 1 0 

- 

User defined 

defined 



pattern for line. 

polyline 

intin(O) = line pattern word 


MSB is first 

vsLudsty 

(16 bits) 


pixel. 

Set 

16 1 100 

— 

On error width is 

polyline 



set nearest below 

width 

p ts in (0) = li n e wi d th p tsout (0 ) = width 

Use odd numbs 

vsLwidth 

(2) = zero 

(2) = zero 

> = three. 

Set poly- 

17 0 0 l 1 * 

— 

Set colour for 

line colour 



polyline ops. 

vsLcolor 

intin(0) = colour index 
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Attribute functions - continued 


Poimpair Integers Device 

Function Op in out in out GDP name 

$0 S2 $4 S6 $8 SA SC 


Comments 


Set 

polyline 
end style 

vs "Lends 


108 0 


0 


intin(0) = start style 
(2) - end style 


— 0 = square ( def t) 

1 = arrow 

2 = rounded 


Set 

polymarker 

type 


18 0 


l 


1 


intin(O) = marker type 

1 = dot 5 = cross 

2 = plus 6 = diamond 


All devices 
support at least 
six markers. 

Defaults on 


vs«i_type 

3 = asterisk 

4 = square 



error to 
ast crick 


Set 

polymarker 

height 

vsnLheight 

19 1 1 0 

ptsin(0) = zero 

(2) = y-axis ht 

0 — Height set is 

nearest below. 
ptsout(0) = x~axis width 
(2) = y-axis height 

Set poly- 
marker colour 

vsm_color 

20 0 0 1 
intin(0) = colour index 

1 * — 

Set colour for 
polymarker ops. 

Set 

character 

12 1 2 

0 

0 — 

Size is of 
character. 


height 

ptsin(0) = zero 
(2) = height 

ptsout^u; = coar wiam 
(2) = char height 


V 

char 

vsLheig 



[ft) = cen wiam 
(6) = cell height 




Set 

107 0 2 

1 

1 * — 

Size is of cell. 


character 

cell 

height 

vst_poi nt 


intin(O) = cell ptsout(O) = char width 

point ptsout(2) = char height 

size ptsout(4) = cell width 

(1/72) ptsout(6) = cell height 


cell 


Set char 
baseline 
vector 

vsLrotation 


13 


0 


1 


Angular range 
0 to 3600 


intin (0) - angle 

requested 
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Attribute functions - continued 


Function 

Point pair Integers 

Op in .out in out GDP 

SO $2 $4 S6 $8 SA 

Device 

name 

SC 

Comments 

Set text 
face 

vsLfont 

21 0 0 1 I * 

intin(0) = face selection 

— 

Face 1 is built 
in (System face) 

Set graph 
text colour 

22 0 0 1 l * 

— 

Set colour for 
next text. 

vsLcolor 

intin(0) = text col, index 


default 1 

Set text 
special 

106 0 0 1 1 * 

— 

Default to 
standard text 

effect 

vst_effects 

intin(0):hits 0 to 5 set effects 

Thickjlightjskew^undcrline, 

outline^shadow 


Effect on if 
bit - 1 

Set 

graphic 

39 0 0 2 2* 

— 

Left /right /centre 
justify. 

text 

intin(0) = 0,1ft l,cntr 2,rt 


Vertical position 

position 

(2) = 3, 4,0, 1,2, 5 respectively 


defaults to 

vst_a1 ignment 

bottom, descent, base, half, ascent, top 


base ( = 0) 

Set fill 
interior 

23 0 0 I I * 

— 

Set future 
polygon fill 

style 

intin(O) = 0 to 4 respectively 


style. 

vsfJnterior 

0_h olio w 3 1 _sol i d ,2_pat re rn ,3_pat te rn ,4. 

.user defined 

Set fill 

24 0 0 1 1 * 

— . 

Set pattern or 

style 

intin(0) = O^n where n = solid colour 


hatch type. 

index 

2,1 to 24 patterns 


No effect if 

vsLstyle 

3d to 12 hatch 


interior hollow* 
solid or usrdef 

Set fill 
colour 
index 

vs Leo lor 

25 0 0 1 1 * 

intin(0) = colour index 


Set future 
polygon fill 
colour 


The set fill style index can be found with the colour command in the ST BASIC 
sourcebook. 


m 

1 
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Attribute functions - continued 


Function 

Op 

so 

Point pair 
in out 

$2 S4 

Integers 

in out GDP 

$6 $8 SA 

Device 

name 

SC 

Comments 

Set fill 

104 

0 0 

1 1 * 

— 

Set on /off 

peri visible 





fill outline 

vsf„perimeter 

in tin(0),O_in visible. 

<>0_visiblc 



Set user 

112 

0 0 16 xn 0 

— 

Pattern 16 

-defined 





words/plane 

till pattern 


intin(0-15) = 

1 st plane 


Bit 15 word one 

vsf_udpat 


(16-31) = 

2nd plane etc. 


upper left bit. 


r denotes intoutQ is actual value of intinQ used. 


fill 


am 


Notation used for 
angular specifications 


1800 


2700 


900 


The set fill style index can be found with the colour command in the ST BASIC 
sourcebook. 
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RASTER OPERATIONS 

Raster operations arc the manipuation of rectangular blocks of bits in memory or 
pixels on screen, the area is defined in memory form definition blocks (MFDB) that 
consists of: 


Offset 



The raster planes word-bit-pixel relationship follows the format shown in the TOS 
overview (Chapter 2), the top left hand corner pixel address being 0,0. 

I he colour index tables take a non-standard form and care should be taken to ensure 
correct colour usage. 


Pixel 

Index 

Colour 

Pixel 

Index 

Colour 

0000 

0 

white 

1000 

9 

grey 

0001 

2 

red 

1001 

10 

light red 

0010 

3 

green 

1010 

11 

light green 

0011 

6 

yellow 

1011 

14 

light yellow 

0100 

4 

blue 

1100 

12 

light blue 

0101 

7 

magenta 

1101 

15 

light magenta 

0110 

5 

cyan 

1110 

13 

light cyan 

0111 

8 

low white 

mi 

1 

black 


Raster operations perform logical translations of the source to the destination over 
the original destination pixel area. The required logic operation is passed as an 
argument in intin(0) as follows: 
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Mode Function 

Mode Function 

0 

D’ = 0 (all white) 

8 

D’ = NOT [S OR D] 

1 

D’ = S AND D 

9 

D’ = NOT[SXORD] 

2 

D’=S AND [NOT D] 

10 

D’ = NOTD 

3 

D’ = S 

11 

D’= S OR [NOT D] 

4 

D’ = [NOT S] AND D 

12 

D’ = NOT S 

5 

D’ = D 

13 

D’ = [NOT S] ORD 

6 

D’ = S XOR D 

14 

D’ = NOT [S AND D] 

7 

D’= S OR D 

15 

D’ = 1 (all black) 


S — Source 
D = Destination 

D’ = Destination pixel final state 

Raster operations 


Mode 3 = replace 
Mode 4 = erase 
Mode 6 = XOR 


Function 


Point pair 
Op in out 

SO $2 $4 


Integers 

in out GDP 

$6 $8 SA 


Device 

name 

SC 


Comments 


Copy 

raster 

opaque 


vro.cpyfm 


109 4 0 1 0 

intin(O) = logic op Source 

cntrl $ E = Address. L of 
source MFDB 

cntrl $ 12 = AddressX of Dest 

destination MFDB 


n a 

I 8>h 

Q 


Copy rect block 
from source to 
destination. 

If source <> desf n 
then source size 
used, 

ptsin a,b,c, 
d,e,f 5 g,h 


Copy 

raster 

trans- 

parent 


121 


0 


r c,d 

I 

a,b I 


Copy mono block 
from source to 
colour desfn 
If src <> desfn 
then source size 
used. 


vrt-cpyffe 


intin(O) = write mode 
(2) = colour for Is 
(4) - colour for Os 
cntrl 3 E = AddressX of 
source MFDB 

cntrl $12- AddressX of Dest 

destination MFDB e 
write mode a replace, ink (2), paper (4) 

b transparent. If src =» 0 then dest ink(2) unused 
c XOR mode. XOR source to planes (2}&(4)unused 
d rev tram If src - 1 then dest paper{4) unused 


| gX 

D 


ptsin ajb,c, 
d,e,fjg,h 


I 

m - i 

Mill ” i* 

Bj 1 

ij^ 

>r\ \ 

Sill ■ j 

! 

:: : 3 
“ 1 


1 

1 

1 


m 

■ 

‘'r: 


J 

1 

] 

1 


Raster operations - continued 


Function 

Point pair 
Op in out 

SO S2 S4 

Integers Device 

in out GDP name 

$6 $8 SA $C 

Comments 

Trans frm 

110 0 0 

0 

0 — 

Toggle raster 

form 




area from 


cntrl $ E- Address. Lof 

(This block 

standard to 


source Mb DB . ,, 

. must be verified) 

device-specific 


cntrl $12- AddressX of 


form. 

vr_trnfm 

destination MFDB 


Get 

105 1 0 

0 

2 — 

Return pixel 

pixel 




value and colour 


ptsin(O) = x coor 

intout(O) - pixel value 

index 

v^et_pixel 

(2) = y coor 


(2) = colour index 
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INPUT FUNCTIONS 

There are two types of input function generally provided by GEM: 

Request and wait for reply, and 
Request and sample current status. 

Only the following are implemented on the Atari ST, 


Input functions 


Function 

Op 

so 

Point pair Integers 

in out in out GDP 

S2 $4 S6 S8 SA 

Device 

name 

SC 

Comments 

Set 

111 

0 0 37 

0 

— 

Redefine cursor 

mouse 

intinCO) 

= x coor in tin(6) = mask colour 

pattern. Bit 15 of 

form 

( 2 ) 

= y coor (8) = data colour 


word I upper left 


(4) 

= Ij reserved 

(usually 1) 

bit of pattern 


(3 A-328) - 16 word cursor mask bits 


Data under 

vsc-form 

(S2A-JJ48) = 16 word cursor data bits 


mask is saved. 

Exchange 

118 

0 0 0 

1 

■ — 

Goto user- written 

timer int 

cntrl 3 

E = Addr.L of new routine 


interrupt routine 

vector 

retin $12 = AddrX of old routine 


on timer tick. 

vex_t i (tiv 

intout(O) - milliseconds per tick 


Intis disabled 

Show 

122 

0 0 1 

0 




cursor 

intin(O) 

- 0, show cursor 






=>0 3 show if no. of show 



v_show_e 

calls — no. hide calls 



Hide cur 

123 

0 0 0 

0 

— 

Hide cursor (deft) 

v_hide_c 

Operates as per ‘show cursor 1 



Sample 

124 

0 1 0 

1 

— 

Retin button state 

mouse 

ptsout(0) = x coor 



Left button LSB 

button state 

(2) = y coor 



1 - button pressed 

vq_ mouse 

intout(0) = return button state 


0 = button up 

Exchange 

125 

0 0 0 

0 



Goto routine on 

button 

cntrl $ 

E = Addr.L user routine 


button state cltig 

change 

retin $ 1 2 = Addr. L old routine 


Uses DO.W for 






button 

vector 





keys as above. 

vex_butv 

(Save and restore registers) 


Intis disabled 
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Input functions 


«!§ 


function 

Point pair Integers 

Op in out in out GDP 

SO £2 S4 S6 SS SA 

Device 

name 

SC 

Comments 

Exchange 

mouse 

movement 

vector 

vex.motv 

126 0 0 0 0 
cntrl 3 E = Addr.L user routine 
retn $12 = Addr.L old routine 
x and y coordinates may be changed 
after being stored in hardware register 


Goto routine on 
mouse movement. 
DG.W&D1.W 
store x & y. 

Intis disabled 

Exchange 

cursor 

change 

vector 

vex„curv 

127 0 0 0 0 

cntrl $ E = Addr.L user routine 
rctin 312 = AddrX old routine 
routine can be used to draw 
special cursor. 


Goto routine on 
cursor state chg 
D0.W&DLW 
store x & y. 

Intis disabled 

Sample 

keyboard 

state 

information 

vq_key_s 

128 0 0 0 1 
mtout(0)j bitO, right shift 
bit 1, left shift 
bit 2, Control 
bit 3, Alternate 


Return state 
of keyboard shift-alt 
- control keys 

0 bit key up 

1 bit key dn 

Functions calling user written code should not enable interrupts. Registers may 
need to be restored. 

The following GEM VD1 functions are not implemented on 
details are included for completeness: 

the Atari ST 3 brief 

Input functions (Not implemented) 



Function 

Point pair Integers 

Op in out in out GDP 

SO S2 S4 S6 S8 SA 

Device 

name 

SC 

Comments 

Set 

input 

mode 

vsin.mode 

33 0 0 2 1 

intin(0) = Logical i/p device 

1 = locator, 2= valuator 
3 = choice , 4 = st ring 
intin(2) = i/p mode ( 1 - req, 2 = sample) 


Set i/p mode for 
device to request 
or sample. 

Imout = mode 
selected 
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Input functions - continued 


i 


Function 


Pointpair Integers 
Op in out in out GDP 

SO $2 $4 $6 $8 SA 


Device 

name 

SC 


Comments 


Input 

locator., 

request 

mode 

vrqJocator 


28 I 1 0 1 

ptsin(O) = init x coor intout(O) = 
(2) = init y coor terminate 

ptsout(O) — final x coor character 
(2) = final y coor (LSByte) 


Ret position of 
locator device* 
Screen tracks 
cursor until 
terminated by 
key /button press 


Input 

locator. 

28 1 1/0 0 0/1 
ptsin(0) = init x coor intout(0) = 

| Ret position 
of locator device 

sample 

(2) = init y coor terminate 

V 

olp’s 

mode 

ptsout(0) = new x coor character 

new coor [ 

1 0 

(cursor 

(2) = new y coor (LSByte) 

key press 

0 1 

change 
event) 
vs m_l ocator 

(A tablet or a mouse terminate 

no i/p 

0 0 

chars begin at 20H, 32dec) 
If 2 locators, either may input 

key press 

Sc new coor 

1 1 

Input 
valuator, 
req mode 

vrq_val uator 

29 0 0 1 2 
intin (0) = init value 
intout (0) = o/'p value 
(2) = terminator 

— Return value of 

valuator device - 
arrow keys, range 
1 to 100. 


Input 


29 


0/2 


Return value of 
device* 


sample 

mode 

intout (0) = new value 

cnirl $8 

event 

(2) = keypress, if event 

' 0 

none 


occurred 

l 

val ch’ge 

vsm_val uator 


2 

keypress 


Input 
choice, 
req mode 

vrq_choice 


30 0 0 1 1 

intin(O) = Init choice number 
(range 1 to device 
dependant maximum) 


Ret choice status 
of device chosen. 
If invalid return 
choice number 


Input 
choice, 
sample mode 

vsni-Choice 


30 0 0 0 1 

intout(O) = 0 S choice number 
cntriSS = 0, nothing occured 
= I, sampled ok 


Ret choice status 
of device chosen. 
intout(O) — 0 if 
unsuccessful* 


■ 

c 

E 

E 

E 


1 

1 

3 

7 


i i n 


i , 

E 1 


1 

Input functions - continued 



■ i 


Pointpair Integers 

Device 


! : 

Function 

- 

Op in out in out 

SO S2 $4 $6 S8 

GDP name 

SA SC 

Comments 

i ■ 

Input 

31 1 0 2 L 

— 

Ret a string from 


string. 

ptsin(O) = scr x coor 

L - array length 

specified device. 

i 

request 

mode 

(2) = scr y coor 
intin(0)=max string length 
(2) = 0, no echo 


Terminate on CR 
or intout full* If 
intin(O) is neg 

; i 

vrq.string 

1 , echo at prsin 


keyboard defD.5 


§ Input 

31 1 0 2 0/>0 



Ret a string from 

i 

i 

string, 

sample 

mode 

ptsin(0)= scr x coor 
(2) - scr y coor 

intin(O) = max string len (abs) 
(2) = Q, no echo 

I s echo at ptsin 


specified device. 
Terminate on CR, 
intout full or 
no more data. If 
intin(0) is neg 

1 

vsHLString 

cntrl(8) = 0, no chars returned 


pg D.5 def kybd. 
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INQUIRE FUNCTIONS 

The inquire functions return the current attribute settings of a specific device. 

Inquire functions 

Point pair Integers Device 

Function Op in out in out GDP name Comments 

SO $2 $4 $6 SS SA SC 


Extended 

inquire 

function 


vq.extnd 


102 0 6 1 45 

intin(O) = 0, open workstation values 
- 1 3 extended inquire 
intout(O) = 0, not screen 


Ret extra device 
info not in the 
open workstation 
call or return 
open workstation 
values. 


= 1, separate sern Alpha 
= 2j common and 

= 3* separate imagegraphics 

= 4, common memo 

ry controller may not be 
(2) = # pallette background colours the same as 
(4)= Text effects supported(op 106) $4E (78) 

(6) = Scaling 0 = no, l = yes 
(8)— Number of planes 
($ A)— Support look up table: 0 - yes, 1 — no 
($ C)= $ 16 x 16 pixel raster ops/s (speed factor) 

($ E)= contour fill capability 

($ 10) = Char rotate 0 = no, 1 = 90° steps only, 2 - continuous 

($12) = $ writing modes available 

($ 14) = Input mode 0 = none, 1 = request, 2 = sample 

($16)= Text alignment 0 = no* l = yes 

($ 18) = Inking ability 0 = no, 1 = yes 

($ 1 A) = Rubberbanding 0 = no, 1 = lines* 

2 = lines & rects 

($ 1 C) = Maximum $ pts, -I = no max 
($ 1 E) = Maximum intin, -I = no max 
($20) = Number of keys on mouse 
($22) = Styles for wide lines: 0 = no, 1 — yes 
($24) = Writing modes for wide lines 
($26-58) = reserved, contain zero words 
ptsoutf0-$16) = reserved, contain zero words 
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Inquire functions 


Function 


Point pair Integers 

Op in out in out GDP 

SO $2 S4 S6 SS SA 


Device 

name 

SC 


Comments 


Inquire 

26 0 0 2 4 

— Ret value of 

colour 

intin(O) = req colour index 

colour index in 

representation 

(2) = 0,ret colour val reqst 

RGB units. 


(0) = l,ret col val available 

Intout(0) = -1 out 


intout(0) = colour index 

of range 


(2) = red intensity(CMOOO) 



(4) = green intensity (0-1 000) 


vq_color 

(6) = blue in tensity (0-1 000) 


Inquire 

35 0 1 O 5 

— Ret all attribs 

current 

ptsout(0) = Iine width 

that affect 

polyline 

(2) = zero 

polylines 

attributes 

intout(0) = line type intout(6) 

— Start end style 


(2) = line colour (8) 

= Finish end style 

vql.attri bates 

(4) = write mode 


Inquire 

36 . 0 I 0 3 

— Ret all attribs 

current 

ptsout(Q) = width 

that affect 

polymarker 

(2) = height 

polymarkers 

attributes 

intout(0) = marker type 



(2) = marker colour 


vqm.aUn bates 

(4) = writing mode 


Inquire 

37 0 0 0 5 

— Ret all attribs 

current 

intout(O) = interior style(f_23) 

that affect Fill 

fill area 

(2) = colour 

areas. 

attributes 

(4) = fill style(f_24) 

f= VDI function 


(6) = writing mode 


vqf_attributes 

(8) = fill perimeter status 


Inquire 

38 0 2 0 6 

— Ret all attribs 

current 

ptsout(O) = char width 

that affect 

graphic 

(2) - char height 

graphic text. 

text 

(4) = cell width 


attributes 

(6) = cell height 



intout(O) = current graphic text face 



vqt_attribute$ 


(2) = current graphic text colour (font) 
(4) = baseline angular rotation (0-3600) 
(6) = horizontal alignment 
(8) = vertical alignment 
($ A) = writing mode (L32) 
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Inquire functions - continued 



Pointpair Integers 

Device 


Function 

Op in o ut in ou t GDP 

name 

Comments 


SO $2 S4 $6 S8 SA 

sc 


Inquire 

116 0 4 n 0 

— 

Ret a rectangle 

text 

intin = no. words in text 


that encloses 

extent 

ptsout (0) — x coor \ bottom 


specified string. 


(2) = y coor left 




(4) “ x coor bottom 




(6) = y coor right 




(8) = x coor top 




(SA) = ycoor right 




($C) =xcoor top 



vqt_extent 

($E) =y coor left 



Inquire 

117 0 3 1 1 

— 

Ret character cell 

character 

intin(O) — char val in ADE form 


width of spec'd 

cell 

ptsout(O) = cell width ptsout(2) = 0 

character 

width 

(4) = left char delta 

(6)=0 

in current 


(8) = right char delta ( 

:sa)=o 

text face 


intout(O) = ADE of inqui re value 



vqt.width 

-1 if invalid character 



Inquire 

130 0 0 1 33 

— 

Return 32 char face 

face name 

intin(O) = Font id ( 1 is base) 


descriptor (text). 

and index 

intout(O) = ID (Vst_font i/e) 



vqt_name 

(2-$40) = 32 ADE codes 

1st 16charsface 



2nd 16 style and weight 

Inquire 

27 2 0 0 n 

— 

Return cell array 

cell 

cntrl $ E = row length colour index 

definition of 

array 

$10 -#. rows array 


pixels. 


return $12 = #. elems/row Used in colour 



return $14 = #. rows Index array 



return $ 1 6 0 = errors, 0 = none, 1 = pixel colour indeterminate 


ptsin(O) = x coor ptsin(2) = y coor (lower left) 


vq_cel larray 


(4) = x coor (6 ) * y coor (upper right) 

imout(O) = colour index array ( I row at a time) 

-1 indicates indeterminate pixel colour 
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Inquire functions - continued 



Point pai r In tegers 

Device 


Function 

Op in out in out 

GDP name 

Comments 


SO $2 $4 S6 SS 

SA SC 


Inquire 

115 0 0 1 1 

— 

Ret’n current i/p 

input 

intin(O) = logical dev. 

1 — locator 

mode for device. 

mode 

intout(O) = i/p mode 

2 = valuator 

3 = choice 

4 — string 

1 = request 


vqin_mode 


2 = sample 


Inquire 

131 0 5 0 2 

— 

Refn current face 

current 

ptsout(O) = max normal cell width 

size information. 

face 

(2) - baseline to bottom 


information 

(4) = max extra skew width 
(6) = baseline to descent line 



(8) - left skew? extra 




($A) = baseline to half distance 
($C) = right skew extra 
($E) = baseline to ascent 

ADE = ASCII 


($10) - zero 


decimal 


($ 12) = baseline to top distance 

equivalent 


intout(0)= 1st char 

in face 


vqUfontinfo 

(2) — last char 

ADE 
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ESCAPE FUNCTIONS 

The escape functions allow the programmer to access special device functions* 


Function 

Op 

so 

Pointpair Integers 

in out in out 

S2 S4 S6 $8 

GDP 

SA 

Device 

name 

SC 

Comments 

Escape 

general 

format 

5 

■ — — ■ 

■ 

id 



Inquire 
addressable 
alpha 
char cells 

vq_chcel Is 

5 0 0 0 2 1 — 
intout(0) = #rows 

(2) = ^columns 

-1 no cursor addressing 

Get # of vertical 
rows & horizontal 
columns for alpha 
cursor. 

Exit 

alpha mode 

v_exit_cur 

5 

0 0 0 

0 

2 


Enter graphics 
mode and exit 
alphameric mode. 

Enter 

alpha mode 

v_enter^cur 

5 0 0 0 0 3 

cursor set to upper left of char cell 


Exit graphics 
mode and enter 
alphameric mode. 

Alpha 
cursor up 

V-Curup 

5 0 0 0 

Do nothing if at top 

0 

4 


Move alpha cursor 
up one row. 

Alpha 

cursor down 

v.curdown 

5 0 0 0 

Do nothing if at bottom 

0 

5 


Move alpha cursor 
down one row 

Alpha 
cursor right 

v_cur right 

5 0 0 0 

Do nothing if right edge 

0 

6 


Move alpha cursor 
right one column. 

Alpha 
cursor left 

5 0 0 0 

Do nothing if at left edge 

0 

7 

— 

Move alpha cursor 
left one column. 


v^curleft 
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functions - continued 


Function 

Pointpair Integers 

Op in out in out 

SO $ 2 $4 S6 S8 

GDP 

SA 

Device 

name 

SC 

Comments 

Home 
alpha cursor 

v^curhome 

5 0 0 0 0 

Home, usually top left 

8 


Move cursor to 
home position. 

Erase to 
end of 
alpha 
screen 

v_eeos 

5 0 0 0 0 

No cursor position change 

9 


Erase from 
current cursor 
position to end 
of screen. 

Erase to 
end of 
alpha 
text line 

v_eeol 

5 0 0 0 0 

No cursor position change 

10 


Erase from 
current cursor 
position to end 
of line. 

Direct 
alpha cursor 
address 

vs_ 

curaddress 

5 0 0 2 0 
intin(0) = row (1 ton) 

(2) = column (1 to n) 

11 

* 

Place cursor at 
specified row & 
column. 

Output 
cursor 
addressable 
alpha text 

v_curtext 

5 0 0 n 0 

n = # chars in string 

intm() - text string in ADE 

12 


Display a string 
of alpha text 
from current 
cursor position. 

Reverse 
video on 

v„rvon 

5 0 0 0 0 

13 


Display following 
text in reverse. 

Reverse 
video off 

v_rvof f 

5 0 0 0 0 

14 


Display following 
text in normal 
video 

Inquire 
current 
alpha cursor 
address 

vq- 

curaddress 

5 0 0 0 2 15 

intout(0) = row# (minimum one) 

(2) = column# (minimum one) 


Return current 
alpha cursor 
position. 
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Escape functions - continued 


Function 

Point pair Integers 

Op in out in out 

SO S2 $4 S6 S8 

GDP 

SA 

Device 

name 

SC 

Comments 

■ 

Inquire 

5 0 0 0 

1 

16 

— 

Return availably 

- 

tablet 

intoutCOJ^O, not available 




status of tablet. 


status 

1 s available 




mouse j j’stk etc. 


vq.tabstatus 






71 

Hard 

5 0 0 0 

0 

17 

— 

Copy screen to 


copy 





specific printer. 

— 

v_hardcopy 

may not be implemented 






Place 

5 2 0 0 

0 

18 

— 

Place crosshair 

e 

graphic 

ptsin(0) = x coor 




on screen. 


cursor at 

(2) = y coor 






location 






EE 

v_dspcur 








Remove 
last graphic 
cursor 

v_rmcur 


19 — 
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The following Escape functions are not implemented on the Atari ST, but are 
included for completeness; as is a discussion on VDI bit image file format. 


Escape functions (Not implemented) 


Function 

Pointpair Integers Device 

Op in out in out GDP name 

SO 32 34 36 $8 SA SC 

Comments 

Form 

5 0 0 0 0 

20 — 

Pages printer but 

advance 



keeps screen 

v_form_adv 



display 

Output 

5 2 0 0 0 

21 — 

Copies specified 

window 

ptsin(0) = x coordinate | 

i window 

window to printer 


(2) - y coordinate 1 

^ corner 

Adjacent pictures 


(4) = x coordinate ] 

i opposite 

may not join. 

v„Qutput_.window (6)=y coordinate 1 

I corner 


Clear 

5 0 0 0 0 

22 — 

Clear screen list 

display 



without paging 

list 



printer 

v.clear jli sp_ 

_lis 



Output 

5 0-2 0 L+2 0 

23 — 

Enables printer 

bit 

cntrl(2) = 0,get coordinates from file 

to process bit 

image 

— 1, upper left specified 

image file. 


ptsin(0) = x upper left 

coordinates 

by specifying 


(2) = y upper left 

if 

or by default 


(4) — x lower right 

specified 



(6) = y lower right , 


Pixel ratio 


intin(0) - Aspect ratio flag 

provides for 


0 - ignore, 1 = pxl ratio, 2 = page ratio 

i printing 


(2) = Scaling 0 = uniform, 1 = x and y circles 


(4) - First char file name (length L) 


v_bi t_i inage 

(2n + 2) = Last (nth) char file name 


Select 

5 0 0 1 1 

60 — 

Allows IBM 

pallette 

intin(0) = 0 3 use red, green, brown 

comparable 


= l,use cya^magenta, white 

pallette 

vs_palette- 

intout(0) = pallette selected 

selection. 


Inquire 5 0 0 0125 91 — Return film drier 

pallette intout 5 sets 25 ADE byte strings descriptor string 

film types 

vqp^f liras 
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Escape Junctions - continued 



Point pair Integers Device 


Function 

Op in out in out GDP name 

SO 82 $4 $6 88 $A $C 

Comments 

Inquire 

5 0 0 0 20 92 

Return film driver 

pallette 

mtout(O) = port # 0 — 1st comms 

status block. 

driver 

(2) = film number (0 to s) 


state 

(4) = lightness control(-3 +3) 1/3 f_stop step 


(6) = 0 noninterlace, 1 = interlace 
(8) = planes(l to 4) 

(ADE format) 

vqp.state 

(SOA-828) = 2 char colour code for 8 colour indexes 

Set 

5 0 0 0 20 93 — 

Set film driver 

pallette 

intout(O) = port no. 0 - 1 st comms 

status block. 

driver 

(2) = film number (0 to 4) 


state 

(4) = lightness entrl(-3 + 3) 1/3 f stop step 


(6) = 0 noninterlace> 1 = interlace 


vsp.state 

($8- S26) = colour codes for 1 6 colours 


Save 

5 0 0 0 0 94 

Save current 

pallette 


driver state to 

driver 


disk 

state 



vsp_save 



Supress 

5 0 0 0 0 95 

Supress user 

pallette 


prompts and error 

messages 

vspjnessage 


messages 

Pallette 

5 0 0 0 1 96 — 

Return error code 

error 

intout(O) — 0, no error 


inquire 

= l y open dark slide for print film 
= 2, no port at specified location 



= 3,pallette not found at port specified 


— 4, video cable disconnected 



= 5,05 does not allow memory allocation 


= 6, not enough memory for buffer 
= 7, memory not deallocated 
= 8,driver file not found 
= 9 yd river file incorrect type 


vq'pLfcrror 

= 1 Ojprompt user to process print film 
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Escape functions - continued 


Function 

Point pair Integers 

Op in out in out GDP 

$0 $2 $4 $6 |8 SA 

Device 

name 

$C 

Comments 

Update 

5 2 0 0 

0 98 

■ — 

Update file 

metafile 

ptsin(0) =min x 



header enabling 

extents 

(2) =min y 

bounding 


application to 


(4) = max x 1 

rectangle 


get indication 

vjneta_ex tents 

(6) = max y 



of a min window. 

Write 

5 n 0 1 

0 99 

— 

Intin and ptsin 

metafile 

ptsin user defined data 



data written to 

item 

in tin user defined data 



metafile with a 


intin(0) = sub-opcode 


sub opcode >100 

v_wnte_meta 

Sub opcodes 0 to 100 reserved 



Change 

5 0 0 1 

0 100 

— 

Rename metafile 

GEM VDI 

intinOpath/ filename up to 


from 

filename 

74 characters 



GEMF1LE.GEM 

vm_f i 1 ename 




to .GEM 


2700 


900 


■►0 


K oca t ion used for 
angular specifications 


1800 <- 
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Bit image file format 


There are two parts to the bit 
image file, a 16 word header, and a 
block of codified raw data. 


Header 
Raw pixel 
data 
IMG file 



upper left x 

upper lefty Bit 

lower right x image 

lower right y 

page width 

page height 

pixel width in microns 

pixel height in microns 

bits per pixel 

zero, reserved 


Source 

device 


Raw data formats 

The four methods of data coding may be mixed in any desired combination within a 
file. 

Run length encoding (default) 


50 Run length 

51 colour index 

data 


<128 bytes 
<256 


Use a two byte subheader to define 
the data, which must be less than 
128 bytes. The pixels may line 
wrap. 


Extended run length encoding 


SO 

$1 

S2 


Op code 
Extended run 

length 

colour index 
data 


-1 

<128 bytes 
<256 


To cater for pixel runs >127, the 
extended run includes a count of 
128 pixels providing a range of 128 
to 255 pixels. The pixel line may 
wrap. 
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Raster encoding 


$0 

Op code 

—2 





SI 

#pix strm 




intn lwrp<! in the fnHowins? 

S2 

packed 

colour 

indices 




format: 


pixels: — ^ 1 

2 

3 

/ 

> 

l- f 

5 6 


bits: 

0 0 0 

1 0 1 

000 

1 1 0 1 

1 ool 1 

oilo 

bytes: 

; 

0 


1 



Use either: 

1 (black and white) 

3 (four colour) 
or 4 (sixteen colour) 

bits per pixel format (offset S 10 in the header). 

Raster run encoding 


SO 

si 

52 

53 


Op code 
repeat count 
#pix strm ■ 
Packed 
colour 
indices 


-3 

<256 


Raster run encoding permits the 
efficient coding of repeated pixel 
patterns. It is in the same form as 
raster encoding but includes a 
repeat count in the header. 


* #pix strm - the number of pixels in the stream 
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Metafile Sub opcodes 

The Metafile functions are not implemented on the Atari ST, but are included for 
completeness of the GEM operating environment. 

Output page (Not implemented) 

There are two reserved GEM output codes for configuring the output page: 

Physical page size, which defines the output area and coordinate window* specifying 
the coordinate system used in the metafile. 


Output page 


Function 

Point pair Integers 

Op in out in out 

SO $2 $4 $6 S8 

Device 
GDP name 

SA SC 

Comments 

Physical 

page 

5 0 0 3 0 

intin(O) = sub opcode 0 

99 — 

Sub opcode 0 

size 

(2) = page width j 
(4) = page height i 

tenths of 

millimeters 


Coordinate 

window 

5 0 0 5 0 99 

intin(0) = sub opcode 1 

(2) = x coor i lower left corner 

(4) — y coor > of window 

(6) = x coor y upper right corner 

(8) = y coor f of window 

Sub opcode 1 


GEM Draw 

There are a number of reserved GEM output codes used by GEM draw: 

Group : Start and end enclose a set of primitives. 

Draw area type primitive; Start and end indicate that enclosed functions arc 
subject to the area type primitive block that follows the start function. 

Attribute shadow: On and off' indicate enclosed primitives are ignored as they are 
used to draw a drop shadow for the first primitive following ‘off. 

Set no line style: Subsequent area type primitives are not outlined. 
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GEM Output codes 


Function 

Point pair Integers 

Op in out in out 

SO S2 S4 S6 S8 

GDP 

SA 

Device 

name 

SC 

Comments 

Start 

group 

5 0 0 1 0 99 

intin(0) = sub opcode 10 of primitives 

— 

Bracket a set 
as a group 

End 

group 

5 0 0 1 

intin(Q) = sub opcode 1 1 

0 

99 

— 

for a GEM DRAW 
application. 

Start draw 
area type 
primitive 

5 0 0 1 

intin(0) - sub opcode 80 

0 

99 


Use the vertices 
of the first 
primitive 
(except text) 

End draw 
area type 
primitive 

5 0 0 1 

intin(0) - sub opcode 81 

0 

99 


to define a 
gem draw area 
type primitive. 

Set 

attribute 
shadow on 

5 0 0 1 

intin(0) = sub opcode 50 

0 

99 


Only draw a 
drop shadow 
on die first 
primitive* 

Set 

attribute 
shadow off 

5 0 0 1 

imin(0) — sub opcode 5 1 

0 

99 


ignore remaining 
shadow primitives 
until next off 
sub — opcode. 

Set no 
line style 

5 0 0 i 

intin(0) = sub opcode 49 

0 

99 

— 

Subsequent area 
type primitives 
not to be outlined 
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GEM AES function calls 

A set of application environment services (AES) function calls are available to the 
programmer, they consist of routines that make extensive use of the VDI function 
calls, and a dispatcher that provides a limited multitasking capability. The GEM 
VDI calls generally manage graphic outputs to peripheral devices, screen, printer 
etc. whereas GEM AES calls usually handle graphics input. The AES calls are 
grouped into eleven libraries that provide a variety of facilities: 

Application library: controls the access to the other AES libraries. 

Event library : responds to user inputs from mouse, keyboard or elapsed time. 

Menu library : text options. 

Object library: data collections that describes a displayed object, eg a box, an 
icon. 

Form library: a means of obtaining information by the use of a list of questions* 

Graphics library : a set of routines for manipulating the outline of a rectangular 
box* 


Scrap library: routines that allow the interchange of data between applications. 

File selector: user selection of a file from a displayed directory or a file via a 
filename and path. 

Window library: manages up to eight GEM AES windows. 

Resource library: provides the interface between the application and its data and 
files. 

Shell library: enables an application to invoke another application and to keep 
track of the calling command and tail* 

Within GEM AES there is a limited multitasking environment created by the 
dispatcher; a routine that activates processes sequentially simulating a multi- 
tasking environment. The dispatcher maintains two process queues, the Teady* 
for processing list and the 'not ready’ list, where processes are typically waiting 
for a user input, an input from another process or a specified time delay. Each 
'ready* process is allowed a predefined period of CPU time before being returned 
to the end of the 'ready* queue, the environment is saved, the queues updated and 
control passed to the next item in the ‘ready* queue. 

Access to the AES functions is through an extended BDQS call and the AES 
parameter block (six long word pointers to the tables; control, global array, input 
and output attributes and input and output addresses). The AES parameter 
block, control table and global array have the following formats: 


fe 

fe 

fe 

m 

\ 

■ 

m 

& 

& 


ts 

E 

c 

E 

m 

■ 

E: 
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AES PARAMETER BLOCK 


Offset 



80 

Control 
table pointer 


84 

Global 

array 


$8 

I/P attrib 
table pointer 

i n t_ i n 

$C 

O/P attrib 
table pointer 

inUout 

810 

I/P address 
table pointer 

addr.in 

$14 

O/P address 
table pointer 

addr_out 

818 




Offset 


SO 

82 

$4 

S6 

88 

$A 


Opcode 
Length i/p coor table 


Length o/p coor table 


Table length 
Hn words 
Length i/p addr table^ jTabie length 
Length o/p addr table (in longwords 


CONTROL TABLE 


Global array 


Offset 


$0 

version 

GEM AES version identification word 

$2 

count 

Max # concurrent apples supported 

54 

id 

Unique application identifier 

86 

private 

Long word user data as required 




8A 

ptree 

Pointer to resource load address tree, initially zero 
Zero : Address of memory allocations 

SE 

reserved 

812 

reserved 

Zero : Memory length; screen colours 

816 

reserved 

Zero 

S1A 

reserved 

Zero 

81E 




The minimum size of an input table is one word, which must contain zero if no 
parameters are being passed. 
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Typical AES application call 

A typical sequence of calls for an application might be; 

Initialize and free unused memory, set up GEM parameter blocks and tables (APPL_ 
INI [10] must be called first). 

Open (virtual) workstation and get the screen resolution. 

Load a resource file, applicable to the current screen resolution and number of 
colours available, into memory. 

Get the address of specific resource objects and store them in memory. 

Get the address of the resource menu bar and call 'display menu . 

Find the size and location of window (WIND_GET)> identify window as a desktop 
(handle = 0), get the windows width/height (get_f i eld = 4) and draw icons. 

Wait for a user action, a keystroke, mouse button click or movement, GEM AES 
message or a specified time delay as either individual occurences or combined 
events. 

Select from the menu, normally by moving the mouse to the menu bar. The message 
buffer is updated automatically and the process waiting for the input is moved to the 
heady list 1 and progressed to the next stage. 

Reserve and then box a space to hold the dialog which is tested for an exit. On exit, 
any highlighting should be deselected. 

Further user selections, could entail keyboard entries, icon selection etc. 

One of the first operations of an application is to create an active window, which may 
be sized, redrawn, updated and finally closed. 

Note that VD1 calls use device handles and AES windows handles - further 
confusion may arise in the use of file handles — they are all different, bewarcl H 1 
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PARAMETER BLOCK SIZE 

The numbers of parameters required by the various functions are detailed in the 
tabular format: 


Integers Addresses 
Function Op in out in out 

SO S2 S4 $6 SS 


Comments 


The table contains details of the parameter inputs and outputs; note that a zero 
indicates a block filled with a zero. 


GEM AES components 


Monitor mouse 
movement and 
display error & sys 
message. Draw 
objects. 


\ 


Resident in memory 
at all times. 


Up to 3 desk accessories 


Desk accessories run in a 
specially designed window 
on top of the GEM desktop 
or any other application. 


Dispatcher 


Update ‘ready’ and L not 
ready* lists of the processes 
on each AES call. Use 
EVNT.TIM to ensure a 
sequencing if there are no 
AES calls. 


Primary 

application 

Word processor 
spreadsheet etc. 


Giruains the ,ACC 
files for the desk 
accessories. 

Up to 3, the files 
remain in memory 
until user exits AES. 







Library 

Limited multitasking 

Desk accessory 


Menu alert 

subroutines 

kernal St dispatcher 

buffer 


buffer 


Screen manager 


Monitor mouse action 
when outside the work 
area. 


The screen manager 
handles all events in the 
border area of the top 
window, then menu bar 
and the drop down menus. 


Drop down menus and 
alert boxes always 
appear on top of a 
window, icon dr dialog 
AES redraws these 
from this buffer when 
the menu is erased. 


Up to 1,4 screen 
capability and faster 
than an application 
redraw. 


Shell 


Runs on top of the limited 
multitasking kernal. 


Handles the passing of control 
from and to applications as 
they are called and terminated. 
The shell also provides a 
graphic or text window as 
required by the application 
through a VDl open 
workstation call. 
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APPLICATION LIBRARY 

The application library functions initialize memory and data structures, terminate 
processes, communicate with other processes and record/replay user actions. 


Function 

Integers Addresses 

Op in out in out 

SO $2 S4 S6 S8 

Comments 

APPLINIT 

10 0 1 0 0 
intout(Q) = application ID 
-1 failure, > = 0 ok 
put in global array 

Initialize application and 
generate data structures 
prior to other AES 
function calls. 

APPLREAD 

pipe. 

112 1 1 0 Read n bytes from message 

int_in(Q) = from pipe ID 
(2) = n bytes read 
int_out(0) = Ojerror 
>0, ok 

addr_in(0) = buffer address of data to be read 

APPI WR ITE 

12 2 1 1 0 Write n bytes to message 

in t_in(0) = to p ipe I D pipe. 

(2) - n bytes write 
int_out(0) — 0, error 
>0, ok 

addr_in(0) = buffer addr of data to be written 

APPL.FI ND 

13 0 I 1 0 

int_out(0) = applic ID 

= -l,not found 
addr_in(0) = address of null 
term 'ted filename 

Find the ID of another 
application in the system. 

The filename must be 8 
characters long, blank fill. 

APPLTPLAY 

actions. 

14 2 1 10 

int_in(0) = # actions 

(2) = speed(l-lOOO0) 
int_out(0) = onc (always) 
addr_in(0) = memory addr 

holding recording 

Replays a series of user 

speed 50 = half 
100 — full 
200 = twice 
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Application library - continued 


Integers Addresses 

Function Op in out in out Comments 

SO $2 S4 S6 $8 


APPL.TR ecoro 

15 1 1 I 0 

Record a series of actions 



1st word 

lo longivard hi 

(6 byte 
record) 

int_in(0) = # actions 
int_out(0) = # recorded 
addr_in(0) - addr in memory 
to store records 

0 = timer 

1 = button 

2 = mouse 

3 = kybd 

elapsed time ms 
0 = up, 1 = dwn /# elks 
x pixels/y pixels 
char/kybd status 

APPI EXIT 

19 0 1 0 0 

Let application library 


in t-OUt(0) = 0 ,er ror cl can up en v i ron m ent when 

>0, ok a pp li c fini sh m aki ng ca 1 Is 
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event library 

The event library routines monitor multiple and individual user inputs providing 
efficient polling of the dock, keyboard, mouse and message pipes. 


■ 


Integers 

Addresses 


Function 

Op 

in 

out 

in 

out 

Comments 


so 

$2 

$4 

S6 

$8 


EVNTJCEY 

20 

0 

1 

0 

0 

Return standard keyboard 


int_out(0) 

= key code press 

code (Appendix D.) 

EVNT.BUTTON 

21 

3 

5 

0 

0 

Return mouse status on 


EVNTJtOUSE 


int_in(0) = wait #clicks 

Mask 

buttmask 

Keystate 

(2) = buttmask 

0x0001 

butt left 

right_shift 

(4) = button state 

0x0002 

2nd butt 

left_shift 

int_out(0) = No. clicks> = 1 

0x0004 

3rd butt 

control 

(2) = x coor j on 

0x0008 

up to 16 

alternate 

(4) = y coor > event 
(6) = button state 

Button 

state bits 0 = up, 
1 = down 


(8) ^keystate 


22 5 5 0 0 

int_in(0) return flag 

(2) = x coor \ area 
(4) = y coor I position 
(6) = width I pixel 
(8) = height * coor 
int_out(G) = Reserved ( = 1} 
(2)-x coor i on 
(4) = y coor > event 
(6) = button state 

(8) = keystate 


Return mouse status on leaving 

specified area 

Return flag 1, on area exit 


Mask 

buttmask 

Keystate 

0x000 I 
0x0002 
0x0004 
0x0008 

butt left 
2nd butt 
3rd butt 
up to 16 

right_shift 

lefushift 

control 

alternate 


Button state bits Q = up, 1 = down 


16 byi 
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Event library - continued 


EVNT_MESAG 


23 


1 


1 


if 


int_out(Q) = Reserved ( = 1) 
addr_in(0) — mess type ID-* 

(2) = ID of sender 
(4) = 0 or length of message 
greater than 1 6 bytes 
(6-14)= extra words 


AddrinQ extra word entries 

A = window handle 


B = x coor 

G = Object index title 

C = y coor 

c H = Object index item 

O 

D = width 

g h I = menu item ID 

E = height 

(op 35 call return) 

F = Page 

J = top/left CM 000 

0-up, I = down 

Mouse 

4 = 1ft, 5 = right 

arrow 

row 2 — up, 3 = down 

click 

col 6 = left, 7 = right 

message 

Messages entered FIFO, where message 

length> 16 byte use APPI READ. 

Reading kills message. 


EVNOIMER 24 2 1 0 0 

int_in ( 0) = lo Ion gword 
(2) — hi time ms 
(0) = Reserved ( = 1) 


Flag message, up to eight 
words, in message pipe. 


ID 

extra 

words 

required 

Message 

function 

10 

GH 

selected menu 

20 

ABCDE 

redraw window' 

21 

A 

move work area to top 

22 

A 

close window 

23 

A 

toggle fuilsize window 

24 

AF 

scroll/page window 

25 

AJ 

move window horizontal 

26 

AJ 

move window vertica 

27 

ABCDE 

resize window 

28 

ABCDE 

move window 

29 

A 

set new top window' 

40 

I 

desk_acc open message 

41 

I 

desk^acc close message 

50 


ct_updatc 

51 


ct_move 

52 


ct_newtop 


Flag application that a 
specified length of time 
has past. 


EVNT_MULT I 


25 16 

int_in(0) : 
( 2 ) = 
( 4 )’ 
(« = 
( 8 ) : 
(IA): 
(SC) = 
CSE): 
(510) : 
( 512 ) > 
( 514 ): 
(516) 
($18); 
($1A) 
($1C) 
(5 IE) 


7 1 0 

= Standard keyboard 
= No, clicks 

- buttmask 

: button state 
= flags 

- x coor 
= y coor 
= width 

- height 
= flags 
= x coor 


event 


= y coor 
■ width 
- height 
-low llongword 
= high ) time ms 


Application waiting on one or 
code more events 


Button state Q_up, Mdown 


Mouse 

1 

area 

event 

Mask 

buttmask 

flags 

0x0001 

0x0002 

butt left 
2nd butt 

Keyboard 

Button 

0x0004 

3rd bun 

Mouse 1 

Mouse 

2 

0x0008 


Mouse 2 

0x0010 


Message 

area 

0x0020 


Timer 


Flags show the type of 
event the application is 
waiting for, or occurred 


continued ... 
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Event library - continued 


Function 


Op 

$0 


Integers 
in out 
$2 $4 


Addresses 
in out 
S6 $ 8 


Comments 


EVNT.MULTI 

continued 


im_out(0) = flag 

(2) = x coor 
(4) = y coor 
(6) = button state 
(8) = keystate 
(8 A) = key code press 
(SC) = # clicks> = 1 


Keystate 


0x000 1 _right shift 
OxGGQ2 Jeft shift 
0x0004_comrol 
Qx0008_alternatc 


Return std kybd code 
# of button events/ time 
addr Jn(0) = 16 byte buffer (see EVNT_MESAG op 23) 


EVNT-DCLJXK 


0 


26 2 1 0 
int_in(0) = slow 0 to 4 
(2) = 0_get, i_set 
int_out(0) = speed l_new O_old 


Get/ set double click 
speed 


Most applications will wait for a combination of events using the EVNT MULTI call. 
When a required event occurs, the application will be moved from the not rea y 
list to the ‘ready’ list by the dispatcher, respond to the event and then return to the 
‘not ready’ list to wait for the next event in the EVNT-MULTI sequence. 

Be careful in using the right hand Atari mouse button, not ail versions of GEM have 
two buttons, when considering portable software. 

Keystroke selection 

Some menu items support keystoke selection through the EVNT_MULT I call. On recapt 
of the specified key selection, the application should call MENILTNORMAL to highlight 
the title to enable the user to see the selection actually made; deselect highlighting 
when the application has finished with the menu. The 16-bit keyboard event codes 
are given in Appendix D; use GRAF_MKSTATE to decode Control, Alternate and left and 

right shift keys, 


Icon selection 

The bits for the required icon selection sequence are set by the application in the 
EVNT MULTI call, button up or down state and a predefined number of clicks within a 
given space of time. On the event taking place, a bit value for the mouse and 
keyboard state is returned; the application needs to also call GRAF.MKSTtt E to obtain 
the mouse’s x and y coordinates and then make an OBJC.FIND call passing the x and y 
coordinates and the address of the window, desktop or application object tree 
containing its icons. 





If 0BJC_FIND reports the mouse covering an icon, its state should be chang 
selected. 

, ^ mver an icon, the application should assume the user will 
If the mouse does not icon, m PR ^ ^ ^ ^ GRAF _ 

select a group of icons by draw g P d then ca it G RAF_RUBBERBOX to 

,o en.ure “11. Th. appltotion should 

STfc- ton. within Che rectangle and change each ton tom normal Co .elec.ed 
OBJ C_CHANGE calls. 

Menu library 

mouse button to make the selection* 


Integers Addresses 

_ ♦ Comments 

Function Op m out m out 

SO $2 S4 S 6 S8 


, in Display/erase menu bar 

MENU_BAR 30 1 1 1 u 

int_in(0) = menu bar 0_erase 3 l_draw 

int_out(0) = error <L_yes 5 + ve_jio 

addr_in(0) = Object tree address that forms this menu 


MENILICHECK 31 2 1 1 0 Display/erase menu item check mark 

int_in(0) = menu item ID 

(2) = 0_clear, l_display (check mark) 
int_out(0) = error 0_yes, + ve_no 
addr_in(0) = Object tree address that forms this menu 


“ “ ” , . n Disable/enable menu item 

HENILI ENABLE 32 2 1 i u 

int_in(0) = menu item I D 

( 2 ) = 0_disablcd, l_enabled (light/dark) 

int_out(0) = error 0_yes, + ve_no 

addrJn(O) = Object tree address that forms this menu 


MENILTNORMAL 33 2 V~ 1 0 Di.plny menu thle in .ever. e video 

int Jn(0) = menu item ID 

(2) = 0_reverse, l_normal video 
int_out(0) - error 0_yes 3 + ve_no 
addr_in(0) = Object tree address that forms this menu 
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Menu library - continued 

Integers Addresses 

Function Op in out in out 

SO S2 S4 $6 S8 


Comments 


MENU-TEXT 


34 1 12 0 Change menu text reverse video 


int_in(0) = menu item ID 
int_out(0) = error CLyes, + ve_no 
addr_in(0) = Addr of new string for this item 
(4) = Object tree addr for this menu 


MENU-REGISTER 35 1 1 1 0 Place desk accessory menu item 

int_in( 0 ) = Desk accessory string on desk menu and ret 

process ID ace’s menu ID 

int_out(0) = menu item ID (0-5) 
addr_in( 0 ) = address of desk_acc menu text string. 


To display a menu bar, call the resource function RSRCLGAODR with the menu bar’s 
(object) details to obtain the long address of the object tree root, call MENU-BAR with 
the address and set the routine to draw. 

Menu bar control 

The AES screen manager controls all user interaction with the menu bar in the 
following manner: 

The user touches an item in the menu bar using the mouse cursor. 

The screen manager receives a message that the cursor has entered the menu bar 
and enters the ‘ready list’* It determines which item in the title bar the cursor 
touched, saves the screen under and displays the ‘titles menu; highlighting menu 
items as the cursor passes over them* 

The application is held in the ‘not ready list while the screen manager has 
initiated open menus* When the user clicks the mouse on a menu item, the screen 
manager sends details of the object tree of the menu selected to the primary 
application’s message buffer* 

The dispatcher checks the ‘not ready 1 list for the application process waiting for 
the message and moves it to the ‘ready' list. 

The EVNTJ1ULT I call returns a flag of the events that occurred, which may be read by 
the application and any action deemed appropriate by the application taken. 

When the action is complete, the menu title is de-high lighted by the application 
making a MENLLTNORMAL call. 
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Object library 

An object, described by a collection of data in a linked list (object tree), can be 
created, deleted, edited, drawn on the screen, and the object’s position on the screen 
found, using the object library routines. 

Object tree 

An object consists of a parent and perhaps a number of different levels of children, 
who always reside within the parents display space. The tree is created by making 
separate calls to the OBJC.ADD routine for each child or loaded from disk using 
RSRC_L0AD* 


level n 
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The object library uses a number of additional tables, as well as the parameter block, 
control table and global arrays, to describe objects. The cables are accessed via the 
resource library routines and are as follows: 


Additional object library word tables 
(bracketed items are longwords) 


Offset 

Object 

Tedinfo 

Iconbl k 

Bitblk 

Applblk 

Parmblk 

(so) 

Nextchild 

| Text j 

i Mask 

| Image 

( Code 

i Tree 

(#2) 

Istchild 

t string 1 

| string 

( pointer 

( pointer 

( pointer 

($4) 

Lastchild 

i Template j 

j Data 

W_arry 

i Loparm 

Objindx 

(S6) 

Otype 

| string | 

[ string 

H_pixl 

( Hiparm 

Old st 

<S8) 

Oflag 

j Vchar j 

j Text 

x = srce 

— 

Newst 

(SA) 

O State 

J pointer 

^ string 

y_srce 

— 

x_coor 

(SC) 

f OSpec 

Font 

Iconic 

fg_col 

— 

y_coor 

($D) 

i 

Reserved 

x^cpos 

0 

— 

W.pixel 

(S10) 

x^coor 

Justify 

y_cpos 

— 

— . 

H_pixel 

($12) 

y_coor 

Color 

x_ipos 

— 

— 

x_cpos 

(SI 4) 

Width 

Reserved 

yjpos 

— 

— * 

y_cpos 

(816) 

Height 

Brdthk 

i_wide 

— 

— 

W^cpxl 

(818) 

. — 

txtlen 

i_hite 



H_cpxl 

(81 A) 

— 

tmplen 

x_tpos 

prefixes 


Loparm 

(81 C) 

(x&y 


y_tpos 

o = object 


Hiparm 

(3 IE) 

rel to 


uwide 

c = char 


0 

(820) 

parent 


t_hite 

i = icon 


■ — 

(822) 

or screen) 

* — 

0 

t= text 




The tables. Filled by the object library routines, are used in performing various 
functions: 

Object Provides data that describes each object, its tree relationship to other 
objects and its location relative to parent (screen if the root)* Predefined object 
values on next page. 

Tedinfo Allows object types Text (21), Boxtext (22), Ftext (29) and Fboxtext 
(30) to be edited, using the object table spec pointer to point to Tedinfo table. 

Iconblh Is used to hold icon (31) data definitions. Object type Icon points here 
with its spec pointer. 

Bitblk Object type Image (23) uses this to draw bit images like cursors and 


icons. 


1 


Sit 


S! 


I 

i 



sr 

m. 







ft! 

■ 





3 

3 

1 
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Applblk Is used to locate and call an application defined routine that draws 
and or changes an object. The object type Progdef (24) spec pointer points here* 

Parnthlk Storage of data used by the application defined routine above 
(applblk) and pointed to by the code pointer. 


Object libraries 

Routines which edit, create and draw data describing objects that appear on the 
screen, boxes, characters, icons etc. 

There are some predefined values for the table entries: 


Graphic types 
of objects 
(Otype) 

Ospec 

points 

to 

Object flags 

(Oflag) 

Object colors 
(color ) 

20 = Box 

— . 

0x0000 = none 

0 = white 

21 — Text 

Tedinfo 

0x0001 = selectable 

1 = black 

22 = Boxtext 

Tedinfo 

0x0002 = default 

2 = red 

23 = Image 

Bitblk 

0x0004 = exit 

3 = green 

24 = Progdef 

Applblk 

0x0008 = editable 

4 = blue 

25 — Invisbox 

— 

0x0010 = rbutton 

5 = cyan 

26 = Button 

Nstrg 

0x0020 = lastobj 

6 = yellow 

27 = Boxchar 

— 

0x0040 = touch exit 

7 = magenta 

28 = String 

Nstrg 

0x0080 = hidetree 

8 = white 

29 = Ftext 

Tedinfo 

0x0100 = indirect 

9 = black 

30 = Fboxtext 

Tedinfo 


10 = Ired 

31 = Icon 

Iconbik 


11 = Igreen 

32 = Title 

Nstrg 


12 = Iblue 

13 = Icyan 

14 = lyellow 

15 = I magenta 


Font types 


3 = system font 
5 — small font 


Colour fields 


15 12 11 8 

7 

6 4 

3 0 

border 

text 

0_tran 

fill 

inside 

colour 

colour 

l_repl 

type 

colour 
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Object states 

{ Ostate) Ospec 32-bit word! byte values 


0x0000 normal 
0x0001 selected 
0x0002 crossed 
0x0004 checked 
0x0003 disabled 
0x0010 outlined 
0x0020 shadowed 



Low word 

High word 

Loto 

byte 

High 

byte 

Box 

colour 

0 

0 

I nv is box 

colour 

brdthk 

0 

Boxchar 

colour 

0 

char 


Bordenhickness 

(brdtkk) 


Allowable valid characters { V char pointer) 


9 

only digits 0 to 9 


A 

only uppercase A to Z and space 


a 

upper and lowercase A to Z and space 


N 

0 to 9, uppercase A to Z and space 


n 

0 to 9, upper and lowercase and space 


F 

all valid DOS filename chars* plus ?, : 


P 

all valid DOS pathname chars, plus \, : , 

?. # 

P 

all valid DOS pathname chars, plus \ . : 


X 

anything 



0 

none 

1 to 128 

inside 

-1 Co -127 

outside 
(in pixels) 


Editable text 


field definitions 

justification 

0 = ed start 

1 - edinit 

2 = edehar 

3 = edend 

(Justify) 

0 = left justified 

1 = right justified 

2 — centered 
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Object libraries - continued 


Integers Addresses 

Function Op in out in out Comments 

SO $2 $4 $6 $8 


OBJ (LADD 40 2 

int_in(0) = 
(2) = 
int_out(0) = 
addr_in(0) = 

1 1 0 Add an object to an object tree, 

= Parent ID 

= Child ID (item to add) 

= error 0_yes* + ve_no 
- Object tree ad dr of parent and child 

QBJC.DELETE 41 1 

int_in(G) - 
mt^out(O) = 
addr_in(G) = 

1 1 0 Delete an object from an object tree 

= Object to delete 
= error 0_yes, +ve_no 
= Object tree address with object in it 

0BJC_DRAW 42 6 

int_in(0) = 
(2) = 
(4) = 
(6)= 
(8) = 
(*A) = 
int_out(0) = 
addr_in(0) = 

110 Draw an object in an object tree 

= start object 

= draw G_ohj only, nth_level 
= x coor 

= y coor Clip 

= width rectangle 

= height 

- error 0_yes, + ve_no 
= Object tree address with object in it 

GBJC.FIND 43 4 

int_in(0) = 
(2) = 
(4) = 
(6) • 
int_out(0) = 
addr_in(0) = 

1 1 0 Find an object under the mouse form 

= search start object 
= levels of search 
= x coor mouse 
^ycoor location 

=-l_no ohj, 0 to n - # of object in tree 
= Object tree address of search start object 

OBJCLOFFSET 44 1 

int_in(0) = 

3 10 Find obj* screen rel x/y coords 

= object to locate 


int_out(0) = error 0_yes, + ve_no 
(2) = x coor relative 
(4) = y coor to screen 

addr_in(0) = Object tree address with int_m(0) in it 
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Object libraries - continued 

Integers Addresses 

Function Op in out in out Comments 

SO S2 S4 $6 $8 


OBJ ORDER 45 2 1 1 0 Reorder an object within a list, 

int Jn(0) = Object to be moved 

(2) = new pos (0 = hot. level , . 1 ... to— 1 top) 
int_out(0) = error 0_yes, + ve_jno 
addr„m(Q) = Object tree address with inuin(O) in it 


0BJC_E0 I T 


46 4 2 1 0 


Edit object text. 


int_in(0) = text object to be edited 
(2) = user input character 
(4) = next character index in text string 
(6) = 0 3 re served 

= I>fmt str using text/template strings 
= 2,validate against Tedinfo valid^char, 
update and display. 

= 3,turn off text cursor 
int_out(0) = error 0_yes, + ve„no 

(2) = next char index after operation 
addr_in(0) = Object tree ad dr of obj with text in it 


OBJ C_CHANGE 47 8 1 1 0 Changes an object’s state 

int_in(0) = object to be changed 
(2) = zero, reserved 
(4) = x coor 
(6) = y coor clip 
( 8 ) — w i dth rect angle 
(8A) = height 

($C) = object state new value 
(8E) — redraw 0_no, l_yes 
inuout(O) = error 0_yes, + ve_no 
addr_in(0) = Object tree address 


To display an icon, calculate the desktop windows work area using a WINDJ3ET call 
and use OBJ C_DRAW to draw the icon in the work area. The icons position within the 
window is held by the Tconblk* structure. 
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Form library 

A set of routines that enable the user to reply to a list of questions, either by 
checking off boxes or entering text. 


Function 

Integers Addresses 

Op in out in out 

SO $2 $4 $6 S8 

Comments 

F0RM_D0 

50 1 1 1 

0 

Monitor interaction with a form. 


int_in(Q) = object number 



int_out(0) = object # that caused the exit 


addr_in(0) = object tree address 


FORM-DIAL 

51 9 1 0 

0 Reserve /Free dialog box screen area. 


int_in(0) — flag 




(2) = x coor 




(4) = y coor 

small Flag: 


(6) = width 

box 

0 — res screen space 


(8) = height 


for dialog box 


i~ 

0 

8 

X 

It 

< 
* 


1 = expanding box 


(SC) = y coor 

large 

2 = shrinking box 


($E) = width 

box 

3 — free screen space 


($10) = height 




int_out(0) “ error 0_ 

yes, l_no 


FORfLALERT 

52 1 1 1 

0 

Display an alert. 


int_in(0) = exit button 

0 = no default exit 


int_out(0) — chosen exit 

1 = 1st exit button 


addr_in(0) — address alert string 

2 = 2nd exit button. . 

F0RM_ERR0R 

53 1 1 0 

0 

Display an error box. 


int,Jn(0) = DOS error code 



int_out(0) - exit button code (as above) 

FORPLCENTER 

54 0 5 I 

0 

Centre dialog box on screen 


int_out(0) - one, reserved 



(2) — x coor 

Of 



w 

II 

8 

5 

centered 



(6) = width 

object 



(8) = height 

tree 



addr_in(0) = dialog object tree address 
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The forms library routines enable the user to respond to a typical printed style of 
form on the screen in a question and answer mode without tying up the applications 
resources. The forms library also provides a consistent application/ user response 
format. 

The forms have three optional types of user response, they are: 

Check a single box 

Check a combination of boxes 

Provide a typed response 

These may be used any number of times in any combination. Finally the user exits 
typically via an ok or cancel button. 

Taking a dialog as an example: 

To display a dialog, which will appear in the centre of the screen, call resource 
function RSRCJjADDR to get the address of the dialogs object tree. Call F0RM_DIAL to 
reserve screen space and then call 0BJC.DRAW to draw the dialog. 

The application should call FORM J)0 to monitor user interaction with the dialog box. 
Where user changes have been made, the application may use OBJC -CHANGE to reset 
initial values, in particular dehighlight selected buttons. It may also be necessary to 
save some changes made to dialogs. 

To exit from the dialog, call FORMlDIAL to release the screen space, the application 
which should be in an EVNT.MULTl wait state can redraw the screen using an OBJ (LD RAW 
calk 

A nicer display may be achieved if FORMJHAL is used to draw expanding and 
shrinking boxes on start up and finish of the dialog sequence. 

Edit keys 

Keys have certain specified meanings for editing the text fields of forms and dialog 
boxes: 


+-and -> : Move left or right within the field, 

\ and t a b : Move to ft rst free spa ce of the next field. 

| : Move to First free space of previous Field . 

delete: Delete character following cursor without moving cursor. 

backspace Delete character to the left of the cursor, move cursor and 
following text one space left. 

return End edit and terminate if either ok or cancel type buttons are 
default objects otherwise ignore. 

escape: Clear all characters from the field. 
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El M 3 
fe = 3 


& | 1 

& | 1 

fci 2 ^ 

n | i 

is, - 3 

5 1 

■■ I 
m = 1 

ii j 3 
ST; i i 
si | 3 

*0 mT, ! ^ 

I 

i 

i 
i 

“ 3 

I, 


■i i 


m\ t 
m* t 


it i 
*i t 


ti t 

fJ J 


Alerts 

Alerts, which are used by GEM AES to handle error conditions, contain one of four 
pictorial designs; nothing, note icon, wait icon and the stop icon, and upto a 
maximum of 5 lines of 40 character width text (each line being seperated by the | 
symbol) and up to 3 exit buttons, each containing up to 20 characters of text. 

A special case alert is the error box which reports errors in DOS terminology 
(Appendix I), 

A typical set of object structures for an alert on a mono screen box with some textual 
information and ok and cancel buttons might be: 


Offset 


Object 

structure 

element 


Box 


HELP OK CANCEL 

Text Boxtext Box text 


Comments 


Pntr to next obj 


0 

nextehild 


1 

2 

3 

0 

2 

lstchild 

1 

-1 

-I 


4 

Lstchild 


5 


-1 

-1 

6 

Otype 

20 

21 

22 

22 

B 

Oflag 

0 

0 

l_selectd 

2_default 

$A 

Ostate 

0 

0 

0 

0 

JSC 

Ospec 

00020007 L 

0L 

0L 

0L 

*10 

x-coor 

90 

Rel 

86 

374 

374 

*12 

y_coor 

150 

to 

16 

18 

50 

*14 

width 

454 

sent 

272 

64 

54 

*16 

height 

98 


64 

16 

16 


-1 root 
-i lowest 
level 


t Relative to parent (Box) 


m t 
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Alerts ~ continued 


Offset 

Tedinfo 

structure 

element 

Box 

HELP 

Text 

OK 

Boxtext 

CANCEL 

Boxtext 

0 

Text string 

— 

help 

ok 

cancel 

4 

Tmpltstrg 

— 

0 

0 

0 

8 

Veharpointer 

— 

0 

0 

0 

$c 

Font 

— 

3 

3 

3 

$D 

Reserved 



0 

0 

0 

810 

justify 

— 

OJeft 

2_center 

2_center 

$12 

colour 

— 

00020000L 00020000L 00020000L 

$14 

Reserved 



0 

0 

0 

$16 

Brdthk 

— 

0 

-2 

“2 

$18 

txtlen 

— 

0 

0 

0 

$1A 

tmplen 

— 

0 

0 

0 


The form library follows the tree from root to children in displaying the form object 
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Graphics library 

The graphics library routines enable the programmer to manipulate the rectangular 
outline of a box. 


Integers Addresses 

Function Op m out in out 

SO $2 S4 S6 $8 


Comments 


0 


G RAF_RUB B ERBOX 70 4 3 0 

int_in(0) = x coor "1 of 
(2) = y coor J box 
(4) = min pixel width 
(6) = min pixel height 
int_out(0) = error 0„yes, + ve_no 

(2) = width 1 when button 

(4) = height J last released 


Draw box expanding & contracting 
from a fixed point with mouse 


GRAFJJRAGBQX 

71 8 3 0 

0 Move a 

box and keep the mouse ptr 


int__ in ( 0) = width 

of 

at same position inside box. 


(2) = height 

box 



(4) = x coor 

being 



(6) = y coor 
(8) = xcoor ~ 

dragged 

Height and width in pixels 


($A) = y coor 

Boundary 



(SC) = width 

rectangle 



($E) = height _ 




int_out(0) = error 

yes, + ve_no 



(2) =» x coor " 

1 when button 



(4) = y coor 

| released 


GFAFJ1GVEB0X 

72 6 1 0 

0 

Draw a moving box 


intJn(0) = width 




(2) — height 




(4) = x coor 

Initial 



(6)== y coor 

position 

Height and width in pixels 


(8) = x coor 

Final 



($ A) = y coor 

position 



int_out(0) = error 0_ 

yes, 4- ve_no 
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Graphics library - continued 


Function 


GBAF_GR0WB0X 


GRAF_SHR 


Integers Addresses 
Op in out in 

SO $2 S4 $6 $8 

73 8 1 0 0 

inUn(O) == x coor 

(2) = y coor Initial 

(4) = width position 

() - height 
() = x coor 

($A) = y coor Final 

(SC) - width position 

(JE) = height 

int_out(0) - error 0_yes, + ve_no 


Comments 


Draw expanding box outline 


i leight and width in pixels 


74 8 1 0 0 

int_in(0) -xcoor 1 

(2) = y coor Final 

(4) -width position 

(6) = height 
(8) = xcoor 

($A) = y coor i Initial 
($C)- width position 

($E) = height 

int_out(0) * error 0_yes, + ve_no 


Draw shrinking box 
outline 


Height and width in pixels 


GRAFJJAT 


75 4 

inUn(O) 


int_out(G) 

addrJn(G) 


1 1 0 
= reserved 
(2) -object tree 
(4) = in the box 
(6) = out of box 


] 


Track mouse pointer 
and button in and 
outside the box. 


obj, 

state 


= 0_outside, Unside the box 
= address object tree containing box 


GRAF_SLI 


76 3 1 1 0 
int_in(0) = parent index 

(2) = object index (slider) 

(4) = motion 0_horiz, Invert 
int_out(0) = OJft/top to 1 000_right, ''bottom 
addr_in(0) = Address object tree 

containing slider & parent 


Keep sliding box 
inside parent box. 


3 - 31 


i 

3 

J 

3 

I 

J 

J 

J 

A 

} 

J 

3 * 

A 

A 

J 

} 

1 


Graphics library - continued 

Integers Addresses 

Function Op in out in out 

SO S2 S4 $6 S8 


Comments 


GRAF _HAN0LE 


GRAF-MOUSE 


77 0 5 0 0 

int_out(0) = VDI handle 

(2) — width ) char cell 
(4) -height f syst. font 
(6) = width ) box for 
(8) = height ( syst, font 


Ret GEM VDi handle for open 
screen workstation 


7g 1110 Permit application to change 

inUn(O) = 0 arrow predefined mouse. 

= 1 text cursor (vertical bar) 

= 2 bee ( hourglass - IBM GEM) 

= 3 hand with pointing finger 
= 4 flat hand, extended fingers 

- 5 thin cross hair 
= 6 thick crosshair 
= 7 outline cross hair 

= 255 mouse form stored in addr_in(0) 

= 256 hide mouse form 

- 257 show mouse form 
int_out(0) = error 0_yes, + ve_no 
addrjn(0) = 35 wd buf: mouse form defn block 


GRAF MKSTATE 79 0 5 0 0 Return mouse location button 

inuout(O) - 1 3 reserved an< 3 keyboard state. 


(2) = x coor i 

mouse 

Mask 

Bum 

Key 

(4) — y coor f 

location 

0x0001 

lift 

Rt SHIFT 

(6) - Butstate 

|0_up 

0x0002 

2nd 

Left SHIFT 

(8) = keystate 

> l_dn 

0x0004 

3rd 

CTRL 



0x0008 


ALT 


GEM AES provides the graphic routines to manipulate the rectangular outline of a 
box which are based on GEM VDI routines. Graphics applications should use 
GEM VDI directly for graphic output to avoid any loss in performance through the 

AES overhead. 
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Scrap library 

The scrap library consists of routines that manage the interchange of information 
between applications. Data is either deleted or copied from the source to the 
clipboard (disk file named scrap), which only holds one document; and then pasted 
(copied) from the clipboard (disk) to the target application. 


Integers Addresses 

Function Op in out in out Comments 

SO S2 $4 $6 $8 


SCRP.READ 80 0 1 1 0 Read the current scrap 

iixt_Qut(G) = error 0 = yes directory on the clipboard 

+ ve no 

addr_in(0) = buffer address into which 
scrap directory is copied. 

SCRP WRITE 81 0 i 1 0 Write new scrap directory 

int_out(0) = error 0 *. yes to clipboard. (Cut & Copy) 

+ ve no 

addrjn(0) = buffer address from which 

scrap directory is copied to clipboard. 


The scrap data is held on disk in a file named scrap , the extension identifies the type 
of data: 

TXT ASCII text string 
.DIF Spreadsheet data 

. G EH Metafile - GEM VD I type graphic images 
IMG Bit image - GEM VD1 standard form 

Applications access the data via GEM RDOS file system calls to: 

Search 
Create a file 
Open a file 
Read a file 
Write a file 
Close a file 
Delete a file and 
Get file size. 


3-83 


File selector library 

The file selector library routine enables the programmer to select file from a 
displayed directory or to type in a filename and path. 


Integers Addresses 


Function 

Op in 

SO S2 

out in out 

S4 S6 $8 

Comments 

FSEI INPUT 

kO 

o 

o 

2 2 0 

Display file selector 


int_out(0) 

(2) 

= error 0 = yes 
4- ve no 

= exit button O^cancel 
l_ok 

box and monitor user 
interaction with it. 


addr_in(0) 

= buffer address of intia! directory specification 
(if not updated holds last dir spec user selected) 


addr_in(4) 

= buffer address of initial selection displayed 


in file selector dialog box (If not updated 
it holds last selection) 


This routine displays a file directory dialog box, the user either selects a filename 
directly from the directory list using a mouse or types in a filename to create a new 
file. 

The file directory dialog box displays the name of the current directory path, a 
selection field, a scrollable directory listing and two buttons to terminate the routine. 
The user interacts with the dialog box in the standard manner, changing the 
directory being displayed, selecting an item from the directory List or typing in a user 
selection and then exiting via the ok OR cancel button. 

The file selector library returns the filename selected or entered, in the buffer at 
addr_in(4), the directory path of the file in the buffer at addr_m(0) and whether the 
selection is ok or is to be cancelled* The application acts upon the information as 
required. 

Entering the underscore into the directory string may cause the ST to crash 


3-84 


Window library 

The window library routines permit the creation, opening, closing and deletion of 
windows to a maximum of eight active windows* The window parameters can be 
recovered or set, the window under the mouse cursor found, a flag set to indicate 
that a window is being updated and the size of a window determined. 


Function 

Integers Addresses 

Op in out in out 

SO $2 S4 S6 S8 

Comments 

WIND_CREATE 

100 5 1 0 0 

intdn(G) = w indow parts 
(2) = x coor Of 

(4) — y coor full 
(6) = width size 

(8) = height window 

int_out(G) = window handle (- 

Allocate window size 
including border & ref n 
window handle, W*dw open 
must set size < = to that 
allocated* 

ve s no windows available) 

W INOPEN 

IQl 5 10 0 Open a window at its 

inuin(O) = window handle initial size and location, 

(2) = x coor -not necessarily its 

( 4 ) = y coor Window' full size* 

(6) — width initial 

(8) =* height size 

int_out(0) = error 0 = yes, +veno 

WIND-CLOSE 

1Q2 l 1 0 0 Close window, does not 

mt_in(0) = window handle deallocate the window' 

int-OHt(O) - error 0 = yes, + ve no or handle. 

WINOELETE 

103 1 1 0 0 Free space occupied by 

intjn(0) = window handle window and handle. 

int_out(0) = error 0 = yes, + ye no 







□ 

2 

n 

n 
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Window parts (bit representation) 

0x0001 

Name 

(name and title bar) 

0x0002 

Close 

(dose box) 

0x0004 

Full 

(full box) 

0x0008 

Move 

(move box) 

0x0010 

Info 

(information line) 

0x0020 

Size 

(size box) 

0x0040 

Up arrow 

(up arrow) 

0x0080 

D narrow 

(down arrow) 

0x0100 

Vslide 

(vertical slider) 

0x0200 

Lfarrow 

(left arrow) 

0x0400 

Rtarrow 

(right arrow') 

0x0800 

Hslide 

(horizontal slider) 


Window library - continued 



Integers 

Addresses 


Function 

Op in 

out 

in out 

Comments 


SO S2 

S4 

S 6 S8 


WINDJjET 

104 2 

5 

0 0 

Get window data specified 





field 


int_m(0) = window handle 



(2)-get_field 



int_out(0) = error 0 

= yes, + ve no 



(2)= _ 

Data 



( 4 ) = 

specified 



(6) = 

by Get 



C8)= . 

field 

- 

WTND_SET 

105 6 

1 

0 0 

Set displayed window' 


intjn(0) 

— window handle 

parameters 


(2) = set_field 



( 4 )= ' 

Data 



(6) = 

specified 



(8) = 

by Set 



(SA) = 

field 



int_out(0) 

= error 0 = yes, +veno 
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Get 

field 

(2) 

ini. 

(4) 

-OUt() 

(6) 

(8) 

Associated function 

4 

x coor 

y coor 

width 

height 

window work area 

5 

x coor 

y coor 

width 

height 

current l size incl border 

6 

x coor 

y coor 

width 

height 

previous | title 

7 

x coor 

y coor 

width 

height 

max possible window size 

8 

1-1000 

1 left, 1000 right 


rel hor slider pos 

9 

1-1000 

1 top, 1000 bottom 


rel vert slider pos 

10 

handle 




top window handle 

11 

x coor 

y coor 

width 

height 

1st rectangle in wind list 

12 

x coor 

y coor 

width 

height 

nxt rectangle in wind list 

13 

reservd 





15 

1-1000 

(-1 default min sq box) 


rel horiz sld size 

16 

1-1000 

(-1 default min sq box) 


rel vert sld size 

17 





screen 


Set 

field 

(4) 

inrOnf j 
(6) (8) 

(SA) 

Associated function 

1 

Parts 



window components 

2 

Name pointer 


address of name string 

3 

Info pointer 


addr info line string 

5 

x coor 

y coor width 

height 

current window size 

8 

1-1000 

1 left, 1000 right 


rel hor slider pos 

9 

10 

1-1000 

handle 

1 top, 1000 bottom 


rel vert slider pos 
top window handle 

14 

lo-word 

hi-word strtobj 


GEM desktop to draw 

15 

1-1000 

(-1 default min sq box) 


rd hor slider size 

16 

17 

1-1000 

(-1 default min sq box) 


rel vertical slider size 
screen 
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Window library - continued 


Integers Addresses 

Function Op in out in out Comments 

SO $2 $4 S6 $8 


WIND_FIND 


WIND_UPDATE 


WINDTALC 


106 2 1 0 0 Find w’dw under mouse 

im_in(0) = x coor "I mouse 
(2) — y coor Jposition 
int_out(G) = window handle 


107 1 I 0 0 Flag about to u’d window 

int_in(0) - update 0 - end s 1 = begin (window locking) 

2 = end, 3 = begin (norm, mouse cntrl) 
int_out(0) = error 0_yes, +ve_no 


108 6 5 0 0 Ret w’dw border/work 

area 

intin(O) — area 0 = work -* border, 1 — border -+ work 
(2) = parts 
(4) = x coor 

(6) = y coor border j wo rk 

(8) = width area values 
(8A) - height ' 
in t_out (0) = err o r 0_y e s , 

-1- ve_no 
(2) = x coor 

(4) — y coor work/border 

(6) = width area values 

(8) = height 


To calculate work 
area, input border 
area values. 

To calc border 
area, input work 
area values. 


The desktop window is always present in the AES environment and supports a 
maximum of eight windows at a time. The AES screen manager handles all the user 
interaction outside the border area and the sizing, dragging and scrolling actions 
requested from within the border. The contents of the border area determine which 
of these functions are available. 

Each user action sends a message through the message pipe to the applications EVN"L 
MBS AG buffer where it is stacked on a first in-first out basis. In order to perform the 
requested function, the message must first be read and then the window manage- 
ment action may be either programmed to be performed or ignored. The assembler 
GEM program (Appendix L) demonstrates the effect of creating a window with the 
facilities, but not incorporating any code to handle the screen managers requests. 
The example also shows the parts handled by the screen manager, moving sliders, 
rubber boxing windows etc. 

The application handles all activities within the windows work area. 
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Note that AES windows do not use the same coordinates as VDI areas: 

AES x, y, width, height 

VDI xl,yl,x2,y2 

To create a window, the application calls 

facilities that the * ^ Reused in all subsequent actions on the window. An 

returning the ^window hand ^ ^ retum thc size 0 f the window work area 

KS to WINM SSgct AES to draw the window’s border area on the screen and 
fend a message to the application to draw the windows work area. 

W1ND.SET calls are used to set the size preview rubber 

sliders. If the window is resized, e _^PP 1 ^ ihfi nearest va lid size or display 

box size is valid. If not, the apphcati > . . t issue a WIND-SET call to 

a warning dialog message. If va i ’ * * ^ L d not re quire the work area to be 

- - — " — 

the windows work a re a ( E V N T _M ES A G 1 D 20) . 

The application is responsible for 

and subsequently to the W rectangle ^XZtZo^TcU that there will 
zero. Note that if the window is not covered, say by the control pane , 

be only one rectangle. 

Before updating the window, the applicate mak^ a 

XdaTon completion ES ‘another WINDJJPBATE call permits further 
change to the display and rectangle lists. 

To redraw the window work area, each rectangle in the rectangle list is compared 
w^ the update rectangle in turn, and any common port, on redrawn. 

To make a window active, 

that includes a mouse button ) ^ ^ ^ window and j therefore 

screen manager - the event anDlicaU on calls WIND_F1ND using the mouse x 

by d* ^ hT^lcrf *e“Lo» ubder the mob*. If i. k d* 

and y coordinates to obtain t, narration of the user selecting desktop 

— » r # ” ds ■ 

£^£55 - - * "■ 

application calls W 1 1SJD_SET to comply . 

DELETE call will then free the handle. 


3 - 


Resource library 

The resource library provides the interface between the application and its file 
Isou c ™ and pictures etc. providing the means to port an 
application to a different environment by simply changing the resource file data. 




Integers 

Addresses 


Function 

Op 

so 

in 

S2 

out 

S4 

in 

S6 

out 

$8 

Comments 

RSRCJ.0AD 

no 

0 

1 

1 

0 

Allocate mem & load a 
resource file. 


int_out(0) = error 0 = yes, + ve no 
addrJn(O) = ASCI I filename string address 


OCTREE 111 0 1 0 0 Free the memory space 

allocated by rsrc_load. 

int_6ut(0) = error 0 = yes, + ve no 


RSRC_GADDR 112 2 1 0 1 Get address of data 

int_in(0) - type structure (object) 

(2) = structure index loaded in memory , 
int„out(0) = error 0 — yes, + ve no 
addr_out(0) = address of specified structure 


Int ege rs A ddre sses 

Function Op in out in out Comments 

$0 S2 S4 S6 SS 


RSRC SADDR 113 2 1 1 o Store the address of a 

int_in(0) = type data structure. 

(2) = struct location index 
int_out(0) - error 0 = yes, + ve no 
addr_in(0) = address of the data structure 


RSRCL0BF1X 114 1 1 1 0 Convert objects location 

int_in(0) = obj index and size from character 

coordinates to pixels. 

inuout(O) = 1, reserved 
addr_in(0)= object tree address 
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Type (of data structure) 


0 tree 

9 template string (tedinfo) 

1 object 

10 valid chars (tedinfo) 

2 ted info 

11 ma sk str i n g ( iconblk ) 

3 icon blk 

12 data string (iconblk) 

4 bitblk 

1 3 tex t st ring ( iconb lk) 

5 string 

1 4 image pointer (bitblk) 

6 imagedata 

15 po inter addr e s s of free st ring 

7 obspec 

1 6 pointer address of free image 

8 text string (ted info) 



To isolate an application from device, user and country specific data and provide 
program portability; GEM AES supports resource files that contain the variable 
parts of the application code. 

To use a resource file, the application makes a RSRCLLOAD call to find the total file size 
in bytes, allocate the memory space for the resource file and update the file for 
screen resolution. The pointers to the object and the tree structures are also updated 
and the address of the tree array stored in the applications * Global array \ 

Access to the object library table pointers may be through RSRC.GADDR and RSRC_SADDR 
calls. The tree index may be accessed via FOROO and MENOAR calls among others, 

RSRC_FREE deallocates the resource file memory and zeroes the tree array address in 
the Global array. 

Resource files are generated using the Atari ST icon edit and resource utility 
program. 
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Shell library 

The shell library routines enable one application to call another and keep track of 
command and command tails. 


Function 

Integers Addresses 

Op m out in out Comments 

$0 S2 $4 S 6 S8 

SHELREAD 

120 0 1 2 0 Let application identify 

in t_ou t(0) = e rror 0 = yes, comman d that cal le d i t i n 

+ ve no fmt of GEM BD O S f . 75 

addr_in(0) - buffer address of command string 
(2) = buffer address of command tail 

SHEL_WRITE 

121 3 1 2 0 Inform GEM which, if 

any, 

int„in(0) = 0 — exit, 1 = run application to run, or exit 

(2) — graphic 0 = no, l = yes GEM AES. 

(4) = GEM applic 0 = no, 1 = yes 
inuout(0)“ error 0- yes, +ve no 
addr_in(0) = new executable command file address 
(2) = command tail address of next program 

SHELGET 

122 1 1 1 0 Get data 

int_in(G) = length 
int_out(0) = error code 
addr_in(0) = buffer address 

SHELPUT 

123 1110 Put data 

int_in(0) = length 
int_out(0) = error code 
addr_in(0) - buffer address 

SHELFIMD 

124 0 1 1 0 Search for filename and 

int_out(0) = error 0 = yes, return full DO S spec 

+ ve no 

addr_in(0) = address 80 character buffer minimum 
i/p search filename 
o/p full DOS filename 

SHELENVRN 

125 0 1 2 0 Search for environment 

i n t_ou t(0) = I , re served parame ter an d store 

address of following byte 
addr_in(0) = pointer to byte storage address 
(2) = search parameter string 
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“nvSr™ 

application might be: 

Exit from GEM AES by m.ktas . SKEUK1T£ =>U with the taU-tO P“«” B “ “ 


zero. 
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Utilities 


INTELLIGENT KEYBOARD COMMAND 
INSTRUCTIONS 

The Atari ST keyboard unit contains a IMH 2 HD 6301 8-bit microprocessor with 
some on-board memory storage to maintain the time of day clock etc. The keyboard 
and its peripheral items, joystick and mouse may be initialized, monitored for 
position or status and the time of day clock read or set. 

The intelligent keyboard (ikbd) communicates with the main processor over a 7.8 
Kbit/s bidirectional serial link, sending individual keycodes or receiving instructions 
and returning status codes in packets of data through a pair of addresses, one for 
transmit and one for receive* 

Characters can be read from the keyboard input queue in main system RAM, it is 
filled by an interrupt routine that transfers data from the ikbd to memory 
automatically. Characters are written to the keyboard by placing the character code 
in the keyboard data register after bit 1 of the keyboard command /status register is 
set* 

Keycodes 

The keyboard transmits make and break keycodes for each key press and release. 
Appendix D provides the codes for the individual keys, bit 7 being set for break and 
cleared for make. 


Data packets 

To differentiate the keyboard codes from the data packets transmitted to and from 
the ikbd to the main processors the codes #|F6 to #$FF precede status information 
packets. The packets provide reports of mouse position and status, time of day and 
joystick status. The packets may be stored and used later, with the header byte 
removed, to restore the condition of the ikbd* 


l<T<r 3'fl Pd* T'M'V'f £4tc -r® utifa 7° 




?€ c \ 1 SuBDvif 

pf \K8WI, -erf 

744? & (if 

47 \ Tivy uS 

(K?s 

(H&piJP taw. / (<? \(o>K &£*) 

ShOPW DC.ff //a, /M \sw 
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IKBD commands 


Input 
op c ode 

Output 

databyte 

Function 

swing 

string 


#$80 

#801 


R ese t. Return keyboard to power-up status 

without affecting dock. 

A break > 200ms also causes a reset. 

#$07 

OOOOOaaa 


Set mouse button action, 
default % 00000000 

1 -press Mouse position report on 

1 .release (only relevant in absolute mode) 



0-button, 1 Jtey type operation. 

#$08 


Set mouse relative position reporting (default). 

Position packet generated asynchronously 
when threshold exceeded. 

#$09 
X msb 
Xlsb 


Set mouse absolute positioning. 

X maximum Resets ikbd x and y coots. 

The x and y values in scaled 

Y msb 

Y 

maximum 

mouse "clicks' do not 

Y Isb 


wrap, 

ignore <0 & >max 

#$0A 
X step 
Y step 


Set mouse key code mode. 

Returns mouse motion in cursor keycodes 
instead of relative or absolute motion records. 

#S0B 
X level 
Y level 


Set mouse threshold. 

Before move event is generated, 
default value 1 . (Relative motion only) 

#$oc 

X 

Y 


Set mouse scale Set X and Y 

Set X and Y scale factors for absolute mouse 
positioning - "clicks 5 per coordinate change. 
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IKBD commands - continued 





Input Output 


op code 

databyte 

Function 


string 

string 



#$ 0D 

#$F7 

Interrogate mouse position 


0000XXXX 

right button down 
right button up \ 

since last interrogation 



left button down\ 

since last 



left button up J 

report 


X msb 1 

X coor 



Xlsb * 


Only valid in absolute 


Y msb i 

Y coor 

mode, regardless of mouse 


Y Isb » 


button action setting. 


#$0E 

Load mouse position. 


#$00 

filler 


Enables user 

X msb 1 

X coor ^ 

1 in scaled 

to preset the 

Xlsb f 

\ 

> coordinate 

internal absolute 

Y msb l 

Y coor ) 

1 system 

mouse position 

Y Isb t 





#80 F 

Set Y = 0 at bottom 

Set for relative and absolute 

#810 

Set Y = 0 at top(default) mouse motions - 

#$11 

Resume 

Resume sending data back. 

#$12 

Disable mouse. 

Stop mouse event reports. Resume 
on any mouse mode command. 

#813 

Pause output 

Stop sending further reports, 
queue them in a finite buffer. 

#814 

Set joystick event reporting (default) 

#815 

Set joystick 
interrogation mode 

Disable joystick event reporting, 
use interrogate to sense jstk state. 

#$16 

Joystick interrogation Return a record of current 

joystick state. 
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IKBD command s - continued — 
Input Output 

opcode databyte Faction 

string string 


#317 

rate 


Set joystick monitoring 
000000 ab [packets of two] 

joystick 1 ) Fire 
Joystick 0 f 


button 


aaaabbbb 


(sample rate 
of 0.01s) 

Set ikbd to monitor 
serial command line 
and joystick 5 update 
time of day clock only 



Set joystick keycode mode (Joystick 0) 

(provides a velocity autorepeat facility) 

Initial rate Final rate 

I Tn Tn Tn Vn Vn IfR “^ 

I | | 1 1 C only Vn 

R n J| times in 0. 1 s matters. 


length of time 


#31A 


Disable joysticks. 

Disable any joystick event generation. 
Valid joystick commands resumes generation 


#31 B 
YY 
MM 
DD 
hh 
mm 
ss 


Set time of day clock 
year \ (S6 s 87 s 88 etc) 



Data sent in packed 
BCD format. 


An invalid 
BCD digit 
does not 
alter the 
existing 
value. 


#$ 1C #3FC Interrogate time of day clock 


YY year 
MM month 
DD day 
hh hour 

mm minute 
ss second 


Data in returned in 
packed BCD format. 
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IKBD commands - continued 


Input 

Output 



op code 

databyte 

Function 


string 

string 



#320 


Memory load 


Addr msb 


1 ikbd controller address 


Addr Isb 


( to be loaded. 


Numb 


Number of data bytes (0-128) 


(data) 




#321 

#$F6 

Memory read 

Status header 

Addr msb 

#320 

) ikbd controller \ 

memory access 

Addr Isb 

data 

) address to be read. 1 



data 

6 bytes of l 



data 

data 

data starting 1 

at address 1 



data 

data 

(addr) / 


#322 


Controller execute 

Allows main system 

Addr msb 


) Ikbd controller 

to call an ikbd 

Addr Isb 


) subroutine address 

subroutine. 

OR 80 


Status inquiries. Get 8 byte data packet 

with the 

#$F6 

Strip packet header and return to recover status 

set 

mode 

#S7 #$8 #$9 #SA #S0B #S0C 


command 

param 1 

code 0 Xmaxb Xstep Xthresh Xtick 



param 2 

0 0 Xmaxl Ystep Ythresh Ytick 



param 3 

0 0 Ymaxh 000 



param 4 

0 0 Ymaxl 000 

ONLY 1 


param 5 

0 0 0 0 0 0 

inquiry 


param 6 

0 0 0 0 0 0 

at a 




time. 


#SF6 

Packet header 



mode 

#3 OF #310 #312 #314 #$15 

#319 #31 A 


param 1 


Rx on 


param 2 

Inquiry on 

Ry 


param 3 

returns 

Tx #300 


param 4 

correct #300 off 

Ty off 


param 5 

mode 

Vx 


param 6 


Vy 

Not valid if in joystick or fire button monitoring mode. 
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When preceding a data packet returned from the keyboard, the special keycodes 
#$F6 to #$FF give the following meanings to the data packets. 


Code 

Dec 

Hex 

Dura packet function 

246 

F6 

Status report 

247 

F7 

Absolute mouse position record 

248 

F8 ) 

i Relative mouse position record 


to 

l 1 1 1 1 1 Oxx (xx = left- right button state) 


FB ] 

\ delta x, 2s complement 



delta y * 2s complement 

252 

FC 

Time of day (resolution of 1 second) 

253 

FD 

Joystick report header (both sticks) 

254 

FE 

xOOQyyyyl x = trigger Joystick 0 event 

255 

FF 

xOOOyy yy J y — st i ck posi tion I oy stick 1 e v ent 


A-LINE ROUTINES 
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Atari ST programmers have access to the VDI primitives via the A-line exception 
routines; they provide a faster performance than the VDI routines* additional 
facilities and use less code to implement. The A-iine routines may be mixed with 
VDI calls or used entirely on their own 5 hut program portability to other systems 
will not be possible. 

The A-line routines operate from a set of variables contained in a data table 
(Appendix F). The table is initialized by activating the A-line exception vector in 
passing the word #$fAOOO. The programmer may then alter or insert variables into 
the data table and call the required function by passing the appropriate function call 
word. 


dc,w 

#$A000 

; initial ize data 

table 

move.w 

#n, d (AO) 

: set function at 

offset d 



; to value n 


dc.w 

#$AQGm 

; cal 1 function 



initialization creates the following pointers: 

dO = base address of A-line variables 

aO = base address of A-line variables 

a l = array of pointers to the 3 system font headers 

a2 = array of pointers to the 15 A-line routines 

(a2 is not returned correctly on disk based versions of TOS) 

If VDI and AES are not used* the variables should be fairly static. If they are used, 
the variables may be changed* registers d0-d2 and a0-a2 will be trashed. 

A-line routines 


Function 

Pointpair Integers 
Op in out in out 

SO $2 $4 S6 $8 

Comments 

Put 

#SA001 10 10 

Plot a pixel at x*y 

pixel 

ptsin(O) = X_msbyte, YJsbyte 



intin(O) = pixel value 


Get 

#$A002 1 0 0 0 

Get the pixel at x*y 

pixel 

ptsin(0) — X_msbyte* YJsbyte return dO = 

pixel value 
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A-Line routines - continued 

Function Parameters Comments 


Line 


#SA0G3 

offset 


^26 XI coordinate 
$28 Yl coordinate 
$2 A X2 coordinate 
$2C Y2 coordinate 
$18 plane 0 
$1A plane 1 
SIC plane 2 
$1E plane 3 
$22 line style mask 
$24 writing mode 
$20 -1 for XOR mode 
else ignore 


Bit 

value 


output 

$22 line style mask 


Draw a line between 
Xl/Yl and X2,Y2 
The line is ALWAYS drawn 
from left to right and the 
mask applied left to right 
also- so watch the phase. 

I Mask is word aligned 
pattern for horizontal 
lines, i.e. any bit 
of mask may used at the 
left -mo st endpoint. 

Mask is rotated to align 
with rightmost endpoint. 


Horiz 

Line 


#$A004 

offset 


26 XI coordinate 
$28 Yl coordinate 
$2 A X2 coordinate 
$18 plane 0 
$1 A plane 1 
$1C plane 2 
$IE plane 3 
$24 writing mode 
$2E Fill pattern pointer 
$32 Fill pattern mask 
$34 Multi-plane fill flag 


Bit 

value 


output 

none 


Draw a line between 
XljYl and X2,Y1 
The line is ALWAYS drawn 
from left to right 


Filled #$AO05 
rectangle 

offset 


26 XI coordinate 
$28 Yl coordinate 
$2 A X2 coordinate 
$2C Y2 coordinate 
$18 plane 0 
$1 A plane 1 i Bit 
$1C plane 2' value 
$1E plane 3 
$24 writing mode 
$2E Fill pattern pointer 
$32 Fill pattern mask 


Draw a filled rectangle 
with upper lefthand corner 
X1 ? Y1 and lower righthand 
corner X2 3 Y2. 


Continued . ♦ , 
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A-Line routines - continued 


Function Parameters Comments 

$34 Multi -plane fill flag 
$36 Clipping flag 
$38 minimum X clipping value 
$3 A maximum X dipping value 
$3C minimum Y clipping value 
$3E maximum Y dipping value 

output 

none 


Line-by 

-line 

filled 

polygon 


#$A006 n 

ptsin(O) = XjY array of 
polygon vertices 

offset $28 Yl coordinate 
$18 plane 0 
$1 A plane ! Bit 

$1C plane 2 value 

$1E plane 3 
$24 writing mode 
$2E Fill pattern pntr 
$32 Fill pattern mask 
$34 Multi-plane fill flag 
$36 Clipping flag 
$38 minimum X clipping value 
$3 A maximum X clipping value 
$3C minimum Y dipping value 
$3E maximum Y dipping value 

output 


Draw 1 scan-line of a 
filled polygon. 


Polygon 

XI jYL..Xn,Yn...XljYl 
Start point must be 
repeated at the end of the 
list 


Yl is the Y coor 
of line to fill. 






Bitblt #SA007 Bit block transfer 

input a6 = i/p parameter table pointer 


output 

none 




Textblt #$A008 




Perform a Text block 

offset 

24 — writing mode 
$6A = Foreground] 

1 Text 

transfer of 1 character. 


$72 = Background j 

[ colour 



$54 = Pointer 



Writing mode 


$58 = Width 


Font 

0-3 VDI modes 


$48 = X coor 


form 

4-19 Bitblt modes 


$4A = Y coor 
$4C = X coor ] 


Character 



$4E — Y coor [ 

( 

on screen 



$50 = width ] 
$52 = height ^ 


Character 

Continued . 
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A -Line routines - continued 


Function 

Parameters 

Comments 


$5 A — Style flag 
$5C = Lighten text mask 
$5E = Skew text mask 
860 = Thickening txt width 
S62 = above 1 Char offset 

864 - below 1 from baseline 

866 = Scaling flag (0 = none) 
840 = Accumulator for x dda 
842 ~ Text bit scale factor 
844 = Scale dir (down > 0) 

868 — Char rotation vector 
846 — Font status 



$6C = Special effects buffer pointer 
$70 = Scaling buffer offset in above pointer 

output 

none 


Show 

#8A009 

Show the mouse, if # of 

mouse 

input none 

‘show’ calls >= # of 


output none 

‘hide* calls. 

Hide 

#$A00A 

Hide the mouse 3 if # of 

mouse 

input none 

'hide* calls exceeds # 


output none 

of 'show' calls. 

Transform 

#$A00R 

Transform mouse form 

mouse 

Cntrl 8E = Addr.L src MFDB 
Cntrl 8 1 2 — Addr. L dest MFDB 
output none 


Undraw 

#$A00C 

Undraw previously drawn 

sprite 

input a2 = sprite slave blk pntr 

sprite 


The sprite save block saves the 
screen underneath the sprite and is 
(tObytes + 64 x # planes) bytes in size. 


output none *** 

a6 smashed *** 
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A-Line routines - continued 


Function Parameters Comments 


Draw #$A0GD Draw a sprite 

sprite input dO = X hot spot (Funct not avaiPbl directly 

dl = Y hot spot on disk- based vs of TO S) 

aQ — pointer sprite definition block 
a 2 = pointer sprite save block 
output none *** a 6 smashed *** 


Copy 

#8A00E 

Copy a raster from source 

raster 

cntrl $E = Addr.L 

(source MFDB) 

to destination* 

form 

cntrl 812- Addr.L 

(destination MFDB) 
output none 



A-line variables table 


offset 


Function 



$00 

0 

Number of video planes i 

Can produce special 

$02 

2 

Number of bytes/ video line # 

effects. 

$04 

4 

Pointer to cntrl array 


$08 

8 

Pointer to intin array 


$oc 

12 

Pointer to ptsin array 


$10 

16 

Pointer to i n tout array 


$14 

20 

Pointer to ptsout array 


$18 

24 

Bit piane_0 



$1A 

26 

Bit plane_l 

current 

colour 

value 


SIC 

28 

Bit plane_2 


81E 

30 

Bit plane_3 


$20 

32 

-1 



822 

34 

VDI line style equivalent 


824 

36 

Writing mode: 0 = replace, 1 = 

transparent 



2 = XOR mode* 3 = inverse transparent 

$26 

38 

XI coordinate 


$28 

40 

Y1 coordinate 


$2A 

42 

X2 coordinate 


$2C 

44 

Y2 coordinate 


$2E 

46 

Pointer to current fill pattern 


$32 

50 

Fill pattern mask (length of pattern) 


Continued . « « 
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A-Line routines - c ontinued^ 

/w™ c “ 


$34 


$36 

$38 

$3A 

$3C 

83E 

$40 

842 

$44 

$46 


$48 
$4A 
$4C 
$4E 
$50 
$52 
$54 
$58 
$5 A 

$5C 

$5E 

860 

862 

864 

$66 

$68 

$6 A 
$6C 
870 
872 
$74 


876 


52 Multi- plane fill pattern 

0_current fill pattern is single plane 
1 .current fill pattern is multi-plane 
54 Clipping flag 0 = no clipping 
56 Minimum x clipping value 
58 Minimum y clipping value 
60 Maximum x clipping value 
62 Maximum y clipping value 
64 Accumulator for textblt x dda 

initialize to 8000H before each call 
66 Textblt scale factor 
68 Scale direction 0 = down 

70 Font status . . 

1 = current font monospaced & may be thickened 
0 = may not be thickened to increase font width 
72 X coor of character in font form 
74 Y coor of character in font form (typically 0) 

76 X coor of character on screen 
78 Y coor of character on screen 

80 Character width 

82 Character height 

84 Pointer to start of font data (font form) 

88 Width of font form . 

90 Style bit 0 = Thicken, bit 1 = lighten, bit 2 - skew 
bit 3 - underline (ignored), bit 4 - outline 
92 Lighten text mask 
94 Skew text mask 
96 Text thickening additional width 
98 Offset above character baseline for skew 
100 Offset below character baseline for skew 
1 02 Scaling flag 0 - no scaling 
1 04 Character rotation vector 0 = horizontal 
900 — vertical down etc. 

106 Text foreground colour 
108 Special effects buffer pointer 

1 12 Scaling buffer offset in above buffer yD] Qnly) 

114 Text background colour (RAM VDI only) 

116 Copy raster form type flag 

0 = opaque type . 

n - plane source to n-plane destination bitblt write mode 

<>G = transparent type 

1 -plane source to n-plane destination VDI write mode 

118 Abort fill routine pointer , 

(Function not available on disk based versions of TOS) 
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Sprite definition block 

offset 


soo 


X offset of hot-spot 


802 


Y offset of hot-spot 


$04 


Format flag 


$06 


Background 1 

Colour 

$08 


Foreground j 

table index 

$0A 


Interleaved 

Background line 0 
Foreground line 0 

$oc 


Background/ 

- 


Foreground 

$4A 


image (32 words) 

Foreground line 16 

84 C 



Format flag 


+ ve 
Fg Bg 

-ve 

Fg Bg 

colour 

plotted 

0 0 

0 

0 

Transparent 

0 1 

0 

1 

Background 

1 1 

1 

1 

Foreground 

1 0 



Foreground 


I 

0 

XOR screen 


Memory form definition block (MFDB) 

offset 


$00 

Memory pointer 

32-bit address of pixel 0>0 

$04 

Width 

) Raster area 

$08 

Height 

J dimensions 

$0C 

Word width 

Pixel width /word size 

$10 

Format flag 

1 

= standardj 0 = device specific 
tfo. planes in raster area 

$14 

Memory planes j 


$18 



Three 

$IC 



reserved 

$20 



words 

$24 


1 J 
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BITBLT table used in block transfers 

Parameter block length must be 76 bytes, the first 52 bytes being set by the user and 
die remainder by the bit. Address register A6 is used as a pointer to the table, a point 
that ‘C programmers should note. 


0 

b_width 

2 

bJieight 

*4 

flplanes 

*6 

fg_col 

*8 

bg_col 

10 

op_table 

H 


12 


13 


14 

s_xmin 

16 

s_yffii n 

18 

s_form 

22 

s„nxwd 

24 

s^nxln ! 

26 

s_nxpl 

28 

d_xmin 

30 

cLymin 

32 

djform 

36 

tLnxwd 1 

38 

tLnxln 

40 

d_nxpl 

*42 

p_addr 



46 

p_nxln 

48 

p^nxpl 

50 

p_mask 


width ) of block in 
height ) pixels 
# of cosecutive planes to bit 
foreground colour high bit j 


Logic op 
index 


SA 

$B 

SC 

SD 


background colour low bit 

logic op - Table of 4 raster op code bytes, 
each containing one of sixteen logical 
operations. They are indexed by fg x 2 + bg for 
each plane -(see below) 

minimum source x 
$10 minimum source y 
$12 source form base address (word b’dry) 

$ 1 6 word in line ) next offset (2 = hi,4 = med,& = lo ) 

$ 1 8 line in p lane J in bytes (90 = hi , 1 60 = med/ lo ) 

$1 A next plane offset from current (always 2) 

$1C minimum destination x 

$1D minimum destination y 

$20 destination form base addr (word boundary) 

$24 word in line 1 next offset (2 = hi ? 4 = med ,8 = lo) 

$26 line in plane ] in bytes (90 = hi, 160 - med/lo) 

$28 next plane offset from current (always 2) 

$2A addr of pattern buffer (0=none) 

A word size repetitive, word aligned pattern that is 
AHDed w r ith the source before being Logically 
combined with the destination. 

$2D next line in pattern ) offset (2, 4, 6 etc) 

$30 next plane in pattern ) in bytes (0 = 1 plane) 

$32 pattern index mask length 


* may be altered during bitbit execution 

The source bit defined by s.xmin, S _ymin, b.width, bjieight is transfered to 
destination d.xnin, d.ymin by the number of planes iterations There is no 

clipping or check that bit blocks are within the encompassing memory forms. 
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Logic Table 




Fg 

bg 

10 

Op^O 

8A 0 

0 

11 

Op_l 

8B 0 

1 

12 

Op_2 

8C 1 

0 

13 

Op_3 

SD 1 

1 


The logic operation bytes (see Chapter 3) specify the effect of foreground and 
background colour bits on the current plane. 
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Interrupt handler 


, t 2 vector $68 (104) and takes the following 

The standard system interrupt is level A 

sequence every interrupt: 

Vertical blank interrupt (VBI) 


Order 


Function 


Sys variable 


Increment the frame counter 

Test for mutual exclusion if = < 0 return 

FRCLOCK , L 

$46 6 

VBSLEM . W 

$452 

Save all the registers on stack 
Increment ‘Vblank counter 
Test for high resolution mode 

if shftmd < 2 then goto 6 test for low resolution 

VBCLOCK.L 
SHFTMD .VJ 

$462 

$44C 

monitor attatched^ 
if yes set mode to zero or 

defshftmd.b 

$44A 

Call cursor blink routine COLORPTR ■ L 

Test for new colour pallette 
if colourptr = 0 then goto 8 
Load pallette with 16 words pointed to by colourptr 

$45 A 

and then zero it. 
Test for new screen 

SCREENPTR. L 

$45 E 


if screenptr = 0 then goto 9 
Set screen physical base to screen pointer an 
then zero pointer . 

9 Run deferred VBI vectors 

# of deferred VBI vectors 
Pointer to VBI vector array 

10 Return 


nvbls ,W 
vblqueue L 


$454 

$456 






v it 

9 1 i 


III 1 

*13 9 


Appendix A 
System variables 


A-2 


The following tables present the system variables in low supervisor space SO to 
$7FF (0 to 2047): 

Exception vectors 


10 

sooo 

Reset initial SSP value 


4 

$004 

Reset initial PC address 


8 

$008 

Bus error 

Dump state 

12 

$00C 

Address error 

and terminate 

16 

$010 

Illegal instr. 

routine pointer 

20 

$014 

Divide by zero Pointer to an RTE 

24 

$018 

Chk instr. 

Dump state 

28 

$01C 

Trapv instr. 

and terminate 

32 

$020 

Privilege viol 

routine pointer 

36 

$024 

Trace mode 


40 

$028 

Line 1010 

A- tine routine pointer 

44 

$02C 

Line 111 I 

Used by AES 

48 

$030 

Unassigned 


52 

$034 

Coprocessor protocol violation (MC68020) 

56 

$038 

Format error (MC68020) 

60 

$03 C 

Uninitialized interrupt vector 

64 

$040 

Unassigned 


* 

- 

— 

Reserved 

82 

$05 C 

Unassigned 


96 

$060 

Spurious interrupt (Hacked to level 3) 

100 

$064 

Int level 1 

(Used if user wants Hblanks) 

104 

$068 

Int level 2 

Horizontal blank sync (H blank) 

108 

$06 C 

Int level 3 

Normal processor interrupt level 

112 

$070 

Int level 4 

Vertical blank sync (Vblank) 

116 

$074 

Int level 5 


120 

$078 

Int level 6 

MK68901 MFP interrupts 

124 

$07 C 

Int level 7 

Non maskable interrupt 

128 

$080 

Trap #0 


132 

$084 

Trap #1 

GEM DOS interface calls 

136 

$088 

Trap #2 

Extended DOS calls 

140 

$08 C 

Trap #3 


176 

$OBO 

Trap #12 


180 

$0B4 

Trap #13 

GEM BIOS calls 

184 

$0B8 

Trap #14 

Atari extended BIOS calls 

188 

$0BC 

Trap #15 


192 

$OCO 

Unassigned 

| 

¥ 

- 

— 

■ Reserved 

252 

$0FC 

Unassigned 

) 
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MFP hardware bound interrupt vectors 


256* 

$100 

Parallel port interrupt_0 (Centronics busy) 

260* 

$104 

RS232 carrier detect (dcd) interrupts 1 

264* 

$108 

RS232 clear to send (cts) imermpt_2 

268* 

$10C 

Graphics bit done interrupt_3 

272* 

$110 

RS232 baud rate generator (Timer D) 

276 

$114 

200Hz system clock (Timer C) 

280 

8118 

Keyboard/ MIDI (6850) interrupts 

284* 

811C 

Polled fdc/_hdc interrupt_5 

288* 

$120 

Horizontal blank counter (Timer B) 

292 

$124 

RS232 transmit error interrupt 

296 

$128 

RS232 transmit buffer empty interrupt 

300 

$12C 

RS232 receive error interrupt 

304 

8130 

RS232 receive buffer full interrupt 

308* 

$134 

User /application (Timer A) 

312* 

$138 

RS232 ring indicator intemipt_6 

316* 

$13C 

Polled monochrome monitor detect interrupt-? 

320 

$140 


¥ 

- 

- 

508 

81FF 



* Initially disabled Priority levels (7 high) 


The polled fdc/_hdc interrupt must be disabled on return. 


Application interrupts 


512 $200 

* 

892 $37C 


Reserved for OEMs 


After an uncaught trap* the processor state is dumped as follows; 


Processor state 


896 

8380 

proc_lives 

Processor state saved if system variable 
set to $12345678 

900 

$384 

proc^regs 

D0-D7/A0-A6, A7_ssp 

964 

$3C4 

proc_pc 

First byte exception number 

968 

S3C8 

proc^usp 

USP 

972 

83CC 

proc_stk 

sixteen words of superstack 


The above values are not overwritten by a system reset, but are by a further crash. 
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System variables 


1024 

1028 

1032 

1036 

$400 
8404 
8408 
$40 C 

L etv_timer 

L etv_critic 

L etv^term 

5 x L etv_xtra 

Timer handoff (logical vector $100) 
Critical error handoff vector ($101) 
Process terminate handoff vect ($102) 
Space for res’d logical vectors ($103-$ 107) 

1056 

$420 

L 

memval id 

#S752019F3 (cold start ok) 

1060 

$424 

B 

memcntl r 

memory controller low nibble 
0 = 128K, 

4 = 5 1 2K, (0 = 256K, 5 = 1 MB 2 banks) 

1062 

$426 

L 

resval id 

#$31415926 to jump through resvector 

1066 

$4 2 A 

L 

resvector 

System reset bailout vector 

1070 

$42 E 

L 

phystop 

Phys RAMtop (points 1st unusable byte) 

1074 

8432 

L 

_menibot 

Available memory bottom (getmpb uses) 

1078 

$436 

L 

_memtop 

Available memory top (getmpb uses) 

1082 

$43A 

L 

memval 2 

#$237698 AA 

1086 

$43E 

W 

flock 

Floppy FIFO lock variable 

1088 

$440 

w 

seekrate 

0 = 6ms, 1 = 12ms, 2 = 2ms, 3 = 3ms default 

1090 

$442 

w 

_timr_ms 

20 (#$14) system timer calibration 

1092 

$444 

w 

_fvemfy 

0 = no write-verify else verify (default) 

1094 

$446 

w 

_bootdev 

System boot device number 

1096 

$448 

w 

palinode 

0 = NTSC, 60Hz else PAL, 50Hz 

1098 

$44A 

B 

defshftmd 

Default video res if monitor changed 

1100 

$44C 

B 

sshiftmd 

Shadow shiftmd hardware register 
0=320x200x4 

1 = 640x200x2 

2 — 640 x 400 x 1 

1102 

$44E 

L 

_v_bas_ad 

Screen mem base pntr (32K contiguous) 
on a 512 byte boundary 

1106 

$452 

W 

vblsem 

Vertical blank mutual exclusion semaphore 
1_ vbiank enabled 

1108 

$454 

w 

nvbls 

8 (No. long words vblqueue points to) 

1110 

$456 

L 

^vblqueue 

Vbiank handler pointer to pointers 

1114 

$45 A 

L 

colorptr 

0 null else pointer to 1 6 word vector 
for hardware pallette next vbiank 

1118 

$45E 

L 

screenpt 

Pointer to screen base next vbiank or 0 

1122 

$462 

L 

_vbclock 

Vertical blank interrupt count 

1126 

8466 

L 

_f re lock 

Count vbiank interrupts not vblsem *d 
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System variables - continued 


1130 

1134 

1138 

1142 

1146 

1150 

846A 

846E 

8472 

8476 

$47A 

$47E 

L 

L 

L 

L 

L 

L 

hdvjnit 

swv_vec 

hdv_bpb 

hdv_rw 

hdv_bodt 

hdvjnediach 

Hard disk initialize vector else zero 
* Monitor changed* vector to follow 
Hard disk vector to return bpb else 0 
Hard disk rd/wr routine vector else 0 
Hard disk boot routine vector else 0 
Disk media change rout vector else 0 

1154 

$482 

W 

_cmdload 

<>0 load & exe COMMAND . PRO (boot dev) 

1156 

8484 

B 

conterm 

Attribute bits for console sys, bit: 
Cabell on ( A G), l_key repeat 
2_keyclick, 3_bios conin() function, 
kbshft in bits 24-31 of DOT 

1157 

$485 

B 


reserved 

1158 

$486 

L 

trpUret 

Saved trap 14 return address 

1162 

$48A 

L 

cri ticret 

Saved return address for etv^critic 

1166 

$48 E 

L 

themd 

GEMDOS memory descriptors 


(don’t change) 


Structure MD 


mj i n k 
m_start 
in_l ength 
m_Gwn 


Next MD/null 
Start of TP A 
Byte size of TP A 
M D 1 s owner/ nu 1 1 




1182 

$49E 

w 

_md 



3 







1186 

$4A2 

L 

savptr 

BIOS register save area pointer 



1190 

$4A6 

W 

_nf lops 

No .floppies attached 0, 1 or 2 



1192 

84 A 8 

L 

constate 

State of conoutQ parser 


1196 

84 AC 

W 

save^row 

Save row# for x-y addressing 

ft- 1 

* 

1198 

84AE 

L 

sav^contxt 

Pointer to saved processor context 

r 

1202 

$4B2 

L 

_bufl 

GEMDOS two buffer-list pointers 







1st buffers data sectors 

, m 1 






2nd buffers FAT and DIR sectors 

» | 

-3 





Structure BCB 







b_T ink Next BCB 

- 1 

_ 





b„bufdrv Drive#/-1 

i 

i 





b_buf typ Buffer type 
b_ b u f r e c Record # cached 


3 





b_di rty Dirty flag 

b_dm Drive media descriptor 

b_bu f r Buffer pointer 



= 

i 
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System variables - continued 


1210 

1214 

1218 

1222 

$4 BA 
S4BE 
S4C2 
$4C6 

L 

L 

L 

L 

_hz_200 

the_env 

_drvbits 

_dskbufp 

Raw 200Hz timer tick 
Default environment string $00000000 
32 bit vector of live block devices 
Pointer to common disk buffer, 

1 Kbyte in systems BSS. 

(Do not use by an interrupt routine) 

1226 

?4CA 

L 

^autopatb 

Pointer to autoexec path (or null) 

1230 

* 

S4CE 

8*L 

_vbU ist 

Initial vblqueue 

* 

1262 

S4EE 

W 

_prt_cnt 

Initially -1. , Alt_Help increments 

1264 

84 FO 

W 

_prtabt 

Printer abort flag 

1266 

$4F2 

L 

^sysbase 

Base of OS pointer (RAM or ROM) 

1270 

84F6 

L 

_shell_p 

Global shell info pointer 

1274 

84FA 

L 

eruLos 

Pointer to end of OS memory usage £ 

1278 

S4FE 

L 

exec_os 

Pointer to shell addr to exec on startup 
(normally 1st byte of AES text seg). 

2048 

$800 


Start of user RAM 


f 


7u\i to 't-i p«7 wlf ** - ffo** 

( it TUrJ i -t f i&i * e * ) 


l fi-l I07fj 

( 4 * >Ud) 
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!” 1 
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Appendix B 
Configuration registers 


s 1 



B - 2 


& 


Configuration Registers (one/_zero) 


MEMORY 

16744452 FF8004 


16745124 FF8240 


r/w 


! 

. .xxxx | 

Memory configurations 


Bank 0 

Bank 1 (not used) 

0 

128Kbyte 

128Kbyte 

1 

128Kbyte 

512 Kbyte 

2 

128Kbyte 

2Mbytc 

3 

reserved 


4 

512Kbyte 

128Kbyte 

5 

512Kbyte 

512Kbyte 

6 

512Kbyte 

2 Mbyte 

7 

reserved 


8 

2Mbyte 

128Kbyte 

9 

2 Mbyte 

512Kbyte 

10 

2 Mbyte 

2Mbyte 

11 

reserved 


12 + reserved 



DISPLAY 

16745061 

FF8201 

r/w 

| xxxxxxxx | 

16745063 

FF8203 

r/w 

|xxxxxxxx| 

16745065 

FFS205 

r 

[xxxxxxxx | 

16745067 

FF8207 

r 

| xxxxxxxx [ 

16745069 

FF8209 

r 

\ xxxxxxxx I 

16745071 

FF820A 

r/w 

I xx| 


r/w I . 


, xxx. xxx^xxx | Pallette 
Invert/ 
XX Blue 



Video base high 
Video base low 
Video address counter high 
Video address counter mid 
Video address counter low 
Sync mode 
External /^Internal sync 
50Hz/_6QHz Field rate 

color 0/0 (border) 
.normal b&w 


16745126 

FF8242 

r/w 

[ xxx. XXX. XXX] 

16745128 

FF8244 

r/w 

1 xxx .xxx , xxx I 

16745130 

FF8246 

r/w 

] xxx. xxx. xxx I 

16745132 

FF8248 

r/w 

1 xxx.xxx.xxxl 

16745134 

FF824A 

r/w 

I . . , . . xxx .xxx . xxx I 

16745136 

FF824C 

r/w 

I . . t , .xxx, xxx. xxx 1 

16745138 

FF824E 

r/w 

I xxx. xxx. xxx] 

16745140 

FF8250 

r/w 

1 , , . . .xxx. xxx. xxx [ 

16745142 

FF8252 

r/w 

I xxx. xxx. xxx 1 

16745144 

FF8254 

r/w 

[ xxx. xxx, xxx] 

16745146 

FF8256 

r/w 

I xxx .XXX . XXX l 


Green 

Red 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 

Pallette 


color 1/1 
color 2/2 
color 3/3 
color 4 
color 5 
color 6 
color 7 
color 8 
color 9 
color 10 
color 1 1 

Continued . 


•I 


£ 

£ 

*£ 


ii 
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-a 

d 

I 

a 

a 

3 

3 

3 

3 

3* 

3 

3 

i 

i 

3 


Configuration registers - continued 


16745148 FFS258 
16745150 FF825A 
16745152 FF825C 
16745154 FF825E 
16745156 FF8260 


r/w |. 

.... xxx . 

xxx , 

, XXX I 

r/w 1 . 

.... xxx . 

xxx 

, XXX I 

r/w |. 

xxx. 

xxx. 

XXX I 

r/w |. 

xxx. 

xxx. 

, XXX 1 

r/w |. 

& 





Pallette color 12 
Pallette color 13 
Pallette color 14 
Pa ilette color 15 
Shift mode 

0 320 x 200j 4 plane 

1 640 x 200, 2 plane 

2 640 x 400, l plane 

3 Reserved 


RESERVED 

16745572 FF340O | | reserved 


DMA/DISK 

16746084 FF8600 

16746086 FF8602 

16746088 FF8604 r/w 

1674609O FF8606 r 


| J reserved 

t | reserved 

| ■ xxxxxxxx | Disk controller 

data access 

I xxx | DMA status 

(mode control) 

.Error 

.Sector count zero 
JData request inactive 



FF8606 



A0 - WD1772 register 
A! - WD1772 register 
HDC/.FDC reg select 
Sect count reg selct 
0 reserved 

Disable/.enable DMA 

FDQLHDC 

Write/.Read 


16746093 

FF8609 

r/w 

| xxxxxxxx | 

DMA base & counter high 

16746095 

FF860B 

r/w 

[xxxxxxxx j 

DMA base & counter mid 

16746097 

FF860D 

r/w 

1 XXXXXXXX I 

DMA base & counter low 
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Configuration registers - continued 
SOUND 


16746596 FF880G 


16746598 FF8802 


| XXXXXXXX I 


1 xxxxxxxx I 


8 bit 

0 

4 bit 

1 

8 bit 

2 

4 bit 

3 

8 bit 

4 

4 bit 

5 

5 bit 

6 

8 bit 

7 

5 bit 

8 

5 bit 

9 

5 bit 

10 

8 bit 

11 

8 bit 

12 

4 bit 

13 


14 


15 


PSG read data 

I/O port B 3 Par i\f data 

PSG register select 

register number 
Channel A fine tune 
Channel A coarse tune 
Channel B fine tune 
Channel B coarse tune 
Channel C fine tune 
Channel C coarse tune 
Noise generator control 
Mixer control-I/O enable 
Channel A amplitude 
Channel B amplitude 
Channel C amplitude 
Envelope period fine tune 
Envel period coarse tune 
Envelope shape 
I/O port A (output only) 
I/O port B (Centronics o/p) 



PSG write data, 
IfOport A 

Floppy side G/_side 1 sel 
FIoppy_drive 0 select 
F loppy _drive 1 select 
RS232 RTS 
RS232 DTR 
Centronics STROBE 
General purpose output 
Reserved 


r/w 1 xxxxxxxx | I/O port B, Par i/f data 






I 




i: 

:! 

5 



Configuration registers - continued 
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MK6S901 

16775681 


16775683 

16775685 

16775687 

16775689 

16775691 

16775693 

16775695 

16775697 

16775699 

16775701 

16775703 

16775705 

16775707 

16775709 

16775711 

16775713 

16775715 

16775717 

16775719 

16775721 

16775723 

16775725 

16775727 


MC6850 

16776192 

16776194 

16776196 

16776198 


FFFA01 | xxxxxxxx [ MFP G*P. J/O 

^ Parallel port status 

■ WD 1772 active 

Interrupt 


FFFA03 

| xxxxxxxx I 

— — Mono monitor 
MFP active edge 

FFFA05 

| xxxxxxxx | 

MFP data direction 

FFFA07 

| xxxxxxxx ( 

MFP interrupt enable A 

FFFA09 

[xxxxxxxx | 

MFP interrupt enable B 

FFFAOB 

1 XXXXXXXX I 

MFP interrupt pending A 

FFFA0D 

| xxxxxxxx I 

MFP interrupt pending B 

FFFA0F 

| xxxxxxxx [ 

MFP intrpt in-service A 

FFFA11 

[ XXXXXXXXl 

MFP intrpt in-service B 

FFFA13 

[XXXXXXXXl 

MFP interrupt mask A 

FFFA15 

J XXXXXXXXl 

MFP interrupt mask B 

FFFA17 

1 xxxxxxxx I 

MFP vector base 

FFFA19 

I xxxxxxxx I 

MFP timer A control 

FFFA1B 

[xxxxxxxx I 

MFP timer B control 

FFFA1D 

[ xxxxxxxx I 

MFP timers C & D control 

FFFA1F 

| XXXXXXXX I 

MFP timer A data 

FFFA21 

| xxxxxxxx I 

MFP timer B data 

FFFA23 

1 xxxxxxxx ] 

MFP timer C data 

FPFA25 

[XXXXXXXXl 

MFP timer D data 

FFFA27 

| xxxxxxxx j 

MFP sync character 

FFFA29 

J XXXXXXXX I 

MFP US ART control reg 

FFFA2B 

1 xxxxxxxx [ 

MFP receiver status 

FFFA2D 

| xxxxxxxx [ 

MFP transmitter status 

FFFA2F 

[xxxxxxxx I 

MFP USART data 


FFFC00 

| XXXXXXXXl 

Keyboard AC I A control 

FFFC02 

[xxxxxxxx I 

Keyboard data 

FFFC04 

[xxxxxxxx I 

Midi AC1A control 

FFFC06 

] XXXXXXXX I 

Midi data 





Appendix C 

Printer and terminal 
escape codes 


C-2 


In general an Atari printer that is designed to work with the ST will provide the 
most suitable path to trouble free computer/printer interfacing and the production 
of hard copy printout and screen dumps. Where a printer of another manufacture is 
to be used 3 the following information may be of use; 

If screen dumps are required, the code 1 B 4C (27 76 decimal) should be recognized as 
‘double density bit image mode’ for printing 960 dots per line at 120 dots per inch on 
8” wide paper (the dump is virtually the same size as the monitor screen display) or 
code 1 B 59 (27 89 decimal) for the wider paper screen dumps. 

It may reasonably be assumed that whatever word processor you employ, it will 
provide the necessary print configuration file to make available the printers facilities. 
Double clicking a non -executable file icon to print its contents should not cause 
problems as control codes are not sent within the text. The ST does however 
precede the file with the code to select draft or NLQ (near letter quality) print, i.e. 
esc , "x H 

Some serial printers are restricted to 2400 and 600 baud operation, the ST supports 
neither rate without recourse to ‘C 3 or assembly language programming. 
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•3 

1 

3 

3 

3 


3 

3 

3 

T 

3 

3 

1 

3 

1 


TYPICAL EPSON PRINTER CODES 


Code Ascii 
Dec Hex Mnem 


Function 


0 00NUL 

1 01SOH 

2 02STX 

3 03 ETX 

4 04 EOT 

5 05ENQ 

6 06ACK 

7 07 BEL Bell 

8 08 BS Backspace 

9 09 HT Tab horizontal 

10 0A LF Linefeed 

11 OB VT Tab vertical 

12 0C FF Formfeed 

13 0D CR Carr. Return 

14 0E SO * Enlarged 

15 OF SI Condensed 

16 10DLE 

17 1 1 DC1 on-line printer 

18 12 DC2 Condensed off 

19 13 DC3 Off-line printer 

20 14 DC4 * Enlarged off 

21 I5NAK 

22 16 SYN 

23 17ETB 

24 1 8 CAN Clear print buffer 

25 19 EM 

26 1A SUB 

27 IB ESC 

28 1C FS 

29 ID GS 

30 IE RS 

31 IF US 


32 

J 

I 


/ 


20 


Printable ASCII codes 


127 7F 


Code ASCII 

Dec Hex Char ESCape code functions 


Dec Hex Char 


ESCape code 


32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 
6! 
62 

63 

64 

65 

66 

67 

68 
69 


41 

42 

43 

44 

45 


# 

$ 


20 
21 
22 

23 

24 

25 % 

26 & 

27 ’ 

28 ( 

29 ) 

2A * 

2B + 

2C , 

2D - Underline on/off 
2E - 
2F / 


Combine print modes 


Sel ROM/user char set 
Define user characters 


Select graphics mode 


30 

31 

32 

33 

34 

35 

36 

37 


Sel vert tab chan 
Set 1/8 inch LF 
Set 7/72 inch LF 
Set 1/6 inch LF 
Set n/216 inch LF 
Italic on 
Italic off 


38 8 

39 9 
3A ; 
3B ; 
3C < 
3D = 
3E > 
3F ? 

40 @ 


A 

B 

C 

D 

E 


Detect paper-out on 
Detect paper-out off 
Copy ROM char to RAM 

* Unidirection print 


Redef. graphic mode 
Initialize printer 
Set n/72 inch LF 
Set vertical Tabs 
n Set form length 
Set horizontal Tabs 
Bold on 


* for one line only 


C - 4 


Typical Epson printer codes - continued^ 


Code Ascii 
Dec Hex Char 


ESC code functions 


Code ASCII 

Dec Hex Char ESCape code functions 


85 

87 


55 U U ni direction on/ off 
57 W Enlarged on /off 


70 

46 

F 

Bold off 

71 

47 

G 

Double strike on 

72 

48 

H 

Double strike off 

73 

49 

I 


74 

4A 

1 

LF n/216 inch 

75 

4B 

K 

60 dpi bitimage 

76 

4C 

L 

120 dpi bitimage 

77 

4D 

M 

Elite on 

78 

4E 

N 

Skip perforation on 

79 

4F 

O 

Skip perforation off 

80 

50 

P 

Pica on /Elite off 

81 

51 

Q 

Set right column 

82 

52 

R 

Select character set 

83 

53 

S 

Super/subscript on 

84 

54 

T 

Super /subscript off 


90 

60 

Z 

240 dpi bitimage 

94 

64 

A 

Set 9 pin bit image 

97 

61 

a 

Set NLQ justify 

98 

62 

b 

Set vert tabs channels 

101 

65 

e 

Set hor/ver Tab increment 

102 

66 

f 

Paperfeed/Tab execute 

108 

6B 

1 

Set left margin 

109 

6C 

m 

Special character generator 

112 

70 

P 

Proportional on /off 

115 

73 

s 

Half speed on/off 

120 

78 

X 

Select draft/ NLQ mode 

1 127 

7F 

del 

Cancel last char 


C - 5 


3 

3 


VT52 TERMINAL ESCAPE CODES 

The following BIOS bconoutQ functions simulate a VT52 terminal, with extensions 
for color, screen wrap etc. 


3 

=3 

3 

3 

3 

3 

3 

3 

3 

3 

3 


i 

3 


Escape Function 

Comments 

A Cursor up 

B Cursor down 

C Cursor right 

D Cursor left 

Up one line, no effect if at top 
Down one line, no effect if at bottom 
Right one position, no effect if at edge 
Left one position, no effect if at edge 

E Clear screen 

H Home cursor 

1 Cursor up 

Clear screen and home cursor to column 0, row 0 
Home cursor to column 0,row 0 
Up one line, if at top scroll 

] Erase to eop 

K Clear to eol 

L Insert line 

M Delete line 

Erase to end of page from and including cursor position 
Clear to end of line from cursor of line position 
Insert blank line with cursor at start of line. 

Move current line down 

Delete cursor line and move remaining lines up one, 
put blank at bottom. 

Y,r,c Cursor r,c 

Position cursor at row r column c 

bjf fg’d colour f 
c 3 b bg 5 d color b 

Color is the 4 lsb of color byte 
Color is the 4 lsb of color byte 

d Erase to 

start of page 

Erase to start of page including the current cursor position 

e Show cursor 

f Hide cursor 

j Save cursor 

k Restore cursor 

Show cursor 
Hide cursor 

Save the cursor position 

Restore cursor, home if no saved position 

1 Erase line 

o Erase to 

line start 

Erase line and move cursor to left edge 

Erase to start of line from and including the cursor 

p Reverse video 

q Normal video , 

Enter reverse video mode 
Exit reverse video mode 

v Wrap at end 

of line 

w Discard end 

of line 

Wrap at end of line and scroll up if necessary 
Overprint line end character with the next character 



» 


I 



Appendix D 
Keycode definitions 



r 
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ASCII CODES 0-127 


Dec 

Ascii 

Dec 

Ascii 

Dec 

Ascii 1 „ 

Dec Ascii 

0 

NUL 

32 

SPACE 

64 

8 

96 


1 

SOB 

33 

t 

65 

A 

97 

a 

2 

STX 

34 

IF 

66 

B 

98 

b 

3 

ETX 

35 

# 

67 

C 

99 

c 

4 

EOT 

36 

S 

68 

D 

100 

d 

5 

ENQ 

37 

% 

69 

E 

101 

e 

6 

ACK 

38 

S 

70 

F ! 

102 

f 

7 

BEL 

39 

' 

71 

G 

103 

9 

8 

BS 

40 

( 

72 

H 

104 

h 

9 

HT 

41 

) ' 

73 

1 

105 

i 

10 

LF 

42 

# 

74 

J 

106 

3 

11 

VT 

43 

+ 

75 

K 

107 

k 

12 

FF 

44 

, 

76 

L 

108 

1 

13 

CR 

45 

- 

77 

H 

109 

m 

14 

SO 

46 


78 

N 

no 

n 

15 

SI 

47 

/ 

i 79 

0 

111 

0 

16 

DLE 

48 

0 

1 80 

P 

112 

P 

17 

DC! 

49 

1 

81 

G 

113 

q 

18 

DC2 

50 

2 

82 

R 

114 

r 

19 

DC3 

51 

3 

83 

S 

115 

s 

20 

DC4 

52 

4 

84 

T 

116 

t 

21 

NAK 

53 

5 

85 

U 

117 

u 

22 

SYN 

54 

6 

86 

V 

118 

V 

23 

etb 

55 

7 

87 

w 

119 

w 

24 

CAM 

56 

8 

88 

X 

120 

X 

25 

EM 

57 

9 

89 

Y 

121 

y 

26 

SUB 

58 


90 

Z 

122 

z 

27 

ESC 

59 


91 

[ 

123 

{ 

28 

FS 

1 60 

< 

92 

\ 

124 

1 

29 

GS 

61 

- 

93 

] 

125 

} 

30 

RS 

62 

> 

94 

A 

126 


31 

US 

J 63 

? 

95 

- 

127 

DEL 


i 
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GSX COMPATIBLE KEYSCAN CODES 


Dec 

Code 

Hex 

Key top 

Dec 

Code 

Hex 

Keytop 

Dec 

Code 

Hex 

Keytop 

l 

01 

ESC 

41 

29 

i 

81 

51 

n.u 

2 

02 

1 

42 

2A 

L SHIFT 

82 

52 

INSERT 

3 

03 

2 

43 

2B 

\ 

83 

53 

DEL 

4 

04 

3 

44 

2C 

Z 

84 

54 

71. U 

5 

05 

4 

45 

2D 

X 




6 

06 

5 

46 

2E 

C 




7 

07 

6 

47 

2F 

V 

95 

5F 

n.u 

8 

08 

7 

48 

30 

B 

96 

60 

iso key 

9 

09 

8 

49 

31 

N 

97 

61 

UNDO 

10 

0A 

9 

50 

32 

M 

98 

62 

HELP 

11 

0B 

0 

51 

33 

, 

99 

63 

kpd ( 

12 

OC 

- 

52 

34 


100 

64 

kpd) 

13 

0D 


53 

35 

/ 

101 

65 

kpd j 

14 

0E 

BS 

54 

36 

R SHIFT 

102 

66 

kpd* 

15 

OF 

TAB 

55 

37 

n.u 

103 

67 

kpd 1 

16 

10 

0 

56 

38 

ALT 

104 

68 

kpd 8 

17 

11 

w 

57 

39 

SPACE 

105 

69 

kpd% 

18 

12 

E 

58 

3A 

CAPS LOCK 

106 

6A 

kpd 4 

19 

13 

R 

59 

3B 

Fl 

107 

6B 

kpd 5 

20 

14 

I 

60 

3C 

f2 

108 

6C 

kpd 6 

21 

15 

Y 

61 

3D 

f3 

109 

6D 

kpd 1 

22 

16 

U 

62 

3E 

f4 

110 

6E 

kpd 2 

23 

17 

l 

63 

3F 

f5 

111 

6F 

kpd 3 

24 

18 

0 

64 

40 

f6 

112 

70 

kpd 9 

25 

19 

P 

65 

41 

f7 

113 

71 

kpd . 

26 

1A 

[ 

66 

42 

f8 

114 

72 

kpd ENT 

27 

IB 

] 

67 

43 

f9 




28 

1C 

RET 

68 

44 

FlO 

116 

74 Left m/j but 

29 

ID 

CNTL 

69 

45 

n.u 

117 

15 Right m/j but 

30 

IE 

A 

70 

46 

n.u 




31 

IF 

S 

71 

47 

HOME 




32 

20 

D 

72 

48 

t 

UK Keyboard 


33 

21 

F 

73 

49 

n.u 




34 

22 

G 

74 

4A 

kpd- 

43 

2B 

# 

35 

23 

H 

75 

4B 


96 

60 

\ 

36 

24 

J 

76 

4C 

n.u 




37 

25 

K 

77 

4D 





38 

26 

L 

78 

4E 

kpd * 




39 

27 

* 

79 

4F 

n.u 




40 

28 

t 

80 

50 

i 





kpd - keypad n.u = not used mjj but = mouse/ joy stick button 

Returned high word lowbyte by RDOS e_eonin function 
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GEM VDI STANDARD KEYBOARD CODES 


Hi 

byte 

Lo 

byte 

Char 

Hi 

byte 

Lo 

byte 

Char 

Hi 

byte 

Lo 

byte 

Char 

03 

00 

CTRl2 

28 

27 

■ 

31 

4E 

N 

IE 

01 

ctrlA 

OA 

28 

( 

18 

4F 

0 

30 

02 

ctrlB 

OB 

29 

) 

19 

50 

P 

2E 

03 

ctriX 

09 

2A 

* 

10 

51 

Q 

20 

04 

ctrlD 

OD 

2B 

+ 

13 

52 

R 

12 

05 

ctrlE 

33 

2C 

* 

IF 

53 

S 

21 

06 

ctrlF 

OC 

2D 

- 

14 

54 

T 

22 

07 

ctrlG 

34 

2E 


16 

55 

U 

23 

08 

ctrlH 

35 

2F 

/ 

2F 

56 

V 

17 

09 

CTRL I 

OB 

30 

0 

11 

57 

w 

24 

OA 

ctrlJ 

02 

31 

1 

2D 

58 

X 

25 

0B 

ctrlK 

03 

32 

2 

15 

59 

Y 

26 

OC 

ctrlL 

04 

33 

3 

2C 

5A 

Z 

32 

0D 

ctrlM 

05 

34 

4 

1A 

5B 

[ 

31 

0E 

ctrlN 

06 

35 

5 

2B 

5C 

\ 

18 

OF 

ctklO 

07 

36 

6 

IB 

5D 

] 

19 

10 

ctrlP 

08 

37 

7 

07 

5E 

A 

10 

11 

ctrlG 

09 

38 

8 

OC 

5F 

_ { ulscore) 

13 

12 

ctrlR 

OA 

39 

9 

29 

60 

i 

IF 

13 

ctrlS 

27 

3A 


IE 

61 

a 

14 

14 

ctrlT 

27 

3B 


30 

62 

b 

16 

15 

ctrlU 

33 

3C 

< 

2E 

63 

c 

2F 

16 

ctrlV 

OD 

3D 

- 

20 

64 

d 

11 

17 

ctrlW 

34 

3E 

> 

12 

65 

e 

2D 

18 

ctrlX 

35 

3F 

? 

21 

66 

f 

15 

19 

ctrlY 

03 

40 

4 

22 

67 

g 

2C 

1A 

ctrlZ 

IE 

41 

A 

23 

68 

h 

1A 

IB 

ctrl[ 

30 

42 

B 

17 

69 

i 

2B 

IC 

ctrl\ 

2E 

43 

C 

24 

6A 

j 

IB 

ID 

Ctrl] 

20 

44 

0 

25 

6B 

k 

07 

IE 

Ctrl 6 

12 

45 

E 

26 

6C 

1 

OC 

IF 

CTRL- 

21 

46 

F 

32 

6D 

eh 

39 

20 

SPACE 

22 

47 

G 

31 

6E 

n 

02 

21 

! 

23 

48 

H 

18 

6F 

0 

28 

22 

11 

17 

49 

I 

19 

70 

P 

2B 

23 

# 

24 

4A 

J 

10 

71 

q 

05 

24 

s 

25 

4B 

K 

13 

72 

r 

06 

25 

% 

26 

4C 

L 

IF 

73 

s 

08 

26 

& 

32 

4D 

M 

14 

74 

t 

n,. 


Continued . . 
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GEM VDI standard keyboard codes - continued 


Hi 

byte 

Lo 

byte 

Char 

Hi 

byte 

Lo 

byte 

Char 

Hi 

byte 

Lo 

byte 

Char 

16 

75 

u 

11 

00 

altW 

71 

00 

*f40 

2F 

76 

V 

2D 

00 

altX 

73 

00 

CTRL*- 

11 

77 

w 

35 

00 

altY 

4D 

00 

-► 

2D 

78 

X 

2C 

00 

altZ 

4D 

36 

SHIFT —* 

15 

79 

y 

3B 

00 

f1 

74 

00 

CTRL— ► 

2C 

7A 

z 

3C 

00 

f2 

50 

00 

1 

1A 

7B 

{ 

3D 

00 

f3 

50 

32 

SHIFTl 

2B 

7C 

1 

3E 

00 

f4 

48 

00 

1 

IB 

7D 

} 

3 F 

00 

f5 

48 

38 

shift! 

29 

7E 

- 

40 

00 

f6 

51 

00 

* page down 

OE 

7F 

DEL 

41 

00 

f? 

51 

33 

* SHIFT PQ 

81 

00 

altO 

42 

00 

f8 



DN 

78 

00 

altI 

43 

00 

f9 

76 

00 

* CTRL PG DN 

79 

00 

alt2 

44 

00 

fIO 

49 

00 

* PAGE UP 

7A 

00 

alt3 

54 

00 

SHIFT FT 

49 

39 

* SHIFT PGUP 

7B 

00 

alt4 

55 

00 

SHIFT F2 

84 

00 

* CTRL PG UP 

7C 

00 

alt5 

56 

00 

SHIFT F3 

77 

00 

CTRL HOME 

7D 

00 

ALT 6 

57 

00 

SHIFT P4 

47 

00 

HOME 

7E 

00 

ALT 7 

58 

00 

SHIFT f5 

47 

37 

SHIFT HOME 

7F 

00 

altS 

59 

00 

SHIFT F6 

52 

00 

INSERT 

80 

00 

alt9 

5A 

00 

shift f7 

52 

30 

SHIFr INSERT 

IE 

00 

ALT A 

5B 

00 

SHIFT f8 

53 

00 

DELETE 

30 

00 

alt8 

5C 

00 

SHIFT F9 

53 

2E 

SHIFT DEL 

2E 

00 

altC 

5D 

00 

shift f 10 72 

00 

* CTRL 

20 

00 

altD 

5E 

00 

*f21 



PRINT 

12 

00 

altE 

5F 

00 

*f22 



SCREEN 

21 

00 

altF 

60 

00 

*f23 

37 

2A 

* PRINT SCRN 

22 

GO 

altG 

61 

00 

*f24 

01 

IB 

ESCAPE 

23 

00 

altH 

62 

00 

*f25 

OE 

08 

BACKSPACE 

17 

00 

altI 

63 

00 

*f26 

82 

00 

ALT- 

24 

00 

altJ 

64 

00 

*f27 

83 

00 

ALT" 

25 

00 

altK 

65 

00 

*f28 

1C 

OD 

CR 

26 

00 

altI 

66 

00 

* f29 

1C 

OA 

CTRLCR 

32 

00 

altM 

67 

00 

*f30 

4C 

35 

SHIFT kpd 5 

31 

00 

altN 

68 

00 

* f31 

4A 

2B 

kpd- 

18 

00 

altO 

69 

00 

* f32 

4E 

2B 

kpd * 

19 

00 

altP 

6A 

00 

* f33 

Of 

09 

TAB 

10 

00 

altQ 

6B 

00 

*f34 

Of 

00 

* BACKTAB 

13 

00 

altR 

6C 

00 

* f35 

4B 

00 


IF 

00 

altS 

6D 

00 

* f36 

4B 

34 

SHIFT-*- 

14 

00 

altT 

6E 

00 

* f37 

4F 

00 

* END 

16 

00 

altI) 

6F 

00 

* f38 

4F 

31 

* SHIFT END 

2F 

00 

altV 

70 

00 

* f39 

75 

00 

* CTRL END 


* These scan codes are not supported by Atari ST BIOS 
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Appendix E - List of callable 
functions 


Code 

Dee Hex 


Function 


(called from trap#13) 


0 

00 

getmpb 

Get & fill memory parameter block 


1 

01 

bconstat 

Return character- device input status 


2 

02 

been in 

Input character to device, ret if done 


3 

03 

bconoiit 

Ooutput character to device, ret if done 


4 

04 

rwabs 

Rd/wr logical sectors to device 


5 

05 

setexc 

Get or set vector number 


6 

06 

tickcal 

Return system timer value (ms) 


7 

07 

getbpb 

Return pointer to BIOS pa ram block 


8 

08 

bcostat 

Return character output device status 


9 

09 

mediach 

Check for media change 


10 

0A 

drvmap 

Set bit map & logical drives 


11 

0B 

kbshft 

Set keyboard shift bits 

— 


Callable from user mode 
Re-entrant to three levels 


Device = 0 
= 1 
= 2 
= 3 
- 4 


Printer 3 parallel port 
Auxj RS232 port 
Con, screen 
Midi 

Keyboard 


Extended ST BIOS calls 


Function f called by trap#14) 


Dec 

Hex 


0 

00 inimaus 

Initialise mouse packet handler 

1 

01 ssbrk 

Reserve X bytes from top memory 

2 

02 _physbase 

Get screen’s physical base address 

3 

03 Jogbase 

Get screen’s logical base 

4 

04 _getrez 

Get screen’s current resolution 

5 

05 ^setScreen 

Set screen’s logical location 

6 

06 ^setPallete 

Set contents of hardware pallette 

7 

07 _setColcr 

Set the pallette number 

8 

08 -floprd 

Read sectors from floppy disk 

9 

09 -flopwr 

Write sectors to floppy disk 
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Extended ST BIOS calls continued 


Dec 

Code 

Hex 


Function ( called by trap#l 4 ) 

10 

OA 

_flopfmt 

Format floppy disk 

11 

0B 

getdsb 

Get device status block pointer 

12 

OC 

midiws 

Write string to MIDI port 

13 

0D 

jnfpint 

Set MFP interrupt number 

14 

0E 

iorec 

Ret pointer to serial device buffer record 

15 

OF 

rscorf 

Configure RS232 port 

16 

10 

keytbl 

Set pointer to keyboard translation tabl 

17 

11 

^random 

Ret 24 bit pseudo random number 

18 

12 

_p rotobt 

Prototype image boot sector 

19 

13 

JHopver 

Verify sectors from floppy 

20 

14 

serdmp 

Dump screen to printer 

21 

15 

cursconf 

Get/set cursor blink /attributes 

22 

16 

settime 

Set keyboard time & date 

23 

17 

gettime 

Get time & date from keyboard 

24 

18 

bioskeys 

Restore keyboard translation tables 

25 

19 

ikbdws 

Write string to interrupt keyboard 

26 

1A 

jdisint 

Disable interrupt no. on MK68901 

27 

IB 

jenabint 

Enable interrupt no, on MK 68901 

28 

1C 

giaccess 

Read,/ write sound chip reg 

29 

ID 

offgvbu 

Set port A bit 0 atomically 

30 

IE 

ongibi t 

Set port A bit I atomically 

31 

IF 

xbtiier 

Set MFP timers & control registers 

32 

20 

dosound 

Set pointer to command bytes 

33 

21 

setprt 

Set /get printer configuration 

34 

22 

kbdvbase 

Ret pointer to keyboard structure 

35 

23 

kbrate 

Get/set keyboard repeat rate 

36 

24 

_pr tbl k 

prtblk primitive 

37 

25 

vsyne 

Wait for next vblank 

38 

26 

supexec 

Execute in super mode 

39 

27 

puntaes 

Throw away AES 


Callable from user mode. 
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GEM BDOS calls 


Dec 

Code 

Hex 


Function (called by trap#l ) 

0 

00 

p.termo 

Terminate process (use $4C) 

1 

01 

c_eoni n 

Read character from standard input 

2 

02 

c.conout 

Write character to standard output 

3 

03 

c_auxin 

Read character from aux device 

4 

04 

c_au scout 

Write character to aux device 

5 

05 

c.prnout 

Write character to standard print device 

6 

06 

c_rawio 

Raw I/O to standard I/O 

7 

07 

c_rawcin 

Raw input from standard input 

8 

08 

c_neci n 

Read character standard input (no echo) 

9 

09 

c_conws 

Write null term $ standard input 

10 

OA 

c.conrs 

Read edited $ from standard input 

11 

0B 

c_conis 

Check status of standard input 

14 

0E 

cLsetdrv 

Set default drive 

16 

10 

c.conos 

Check status of standard output 

17 

11 

c_prnos 

Check stat standard print device 

18 

12 

c.auxi s 

Check stat standard aux device input 

19 

13 

c_auxos 

Check stat standard aux device output 

25 

19 

d_getdrv 

Get default drive 

26 

1A 

f.setdta 

Set disk transfer address 

42 

2A 

t_getdate 

Get date 

43 

2B 

t_setdate 

Set date 

44 

2C 

t_ge tt i me 

Get time 

45 

2D 

t.settime 

Set time 

47 

2F 

f_getdta 

Get disk transfer address 

48 

30 

severs ion 

Get version number 

49 

31 

p_termres 

Terminate and stay resident 

54 

36 

d_free 

Get drive free space 

57 

39 

d.create 

Create a subdirectory 

58 

3A 

d_del ete 

Delete a subdirectory 

59 

3B 

cLsetpath 

Set current directory 

60 

3C 

f_c reate 

Create a file 

61 

3D 

flopen 

Open file 

62 

3E 

f_close 

Close file 

63 

3F 

f.read 

Read file 

64 

40 

f_write 

Write file 

65 

41 

f .delete 

Delete file 

66 

42 

f^seek 

Seek file pointer 

67 

43 

f_att rib 

Get/ Set file attribute 

69 

45 

f.dup 

Duplicate file handle 

70 

46 

f_force 

Force file handle 

71 

47 

d.getpath 

Get current directory 


GEM BDOS calls continued 


Code Function (called by trapUl ) 

Dec Hex 


72 

48 

1 oc 

Allocate memory 

73 

49 

m_f ree 

Free allocated memory 

74 

4A 

Bushrink 

Shrink size of allocated memory 

75 

4B 

p.exec 

Load or execute a process 

76 

4C 

pjierni 

Terminate process 

78 

4E 

f_sfirst 

Search for 1st occurence of filspee 

79 

4F 

f.snext 

Search for 2nd occurence of filspee 

86 

56 

forename 

Rename a file 

87 

57 

f_datime 

Get/set file date & time stamp 


Extended ST BDOS function calls 


Code Function ( called by rrap#2) 

Dec Hex 


0 00 
115 73 


System reset 
VDI access 


System /program control 
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GEM VDI functions 


Op 

code 

Definition 

■Scrrc 

Output device 
Prnt Plot 

Mfil 


Open workstation Use virtual 

X 

X 

X 

X 

*2 

Close workstation workstation 

X 

X 

X 

X 

3 

Clear workstation 

X 

X 

X 

X 

4 

Update workstation 

X 

X 

X 

X 

5 

Escape code 






1 Inquire address character cells 

X 

X 

X 

X 


2 Exit alpha mode 

X 



X 


3 Enter alpha mode 

X 



X 


4 Cursor up 

X 





5 Cursor down 

X 





6 Cursor right 

X 





7 Cursor left 

X 





8 Home cursor 

X 





9 Erase to screen end 

X 





10 Erase to line end 

X 





1 1 Direct cursor address 

X 





12 Output cursor addressable text 

X 





13 Reverse video on 

X 





14 Reverse video off 

X 





15 Inquire cum alpha cursor add 

X 





16 I nqu ire tablet sta tus 



X 



17 Hard copy 


X 




1 8 P lace g ra ph ic cursor 

X 





19 Remove last graphic cursor 

X 




* 

20 Form advance 


X 


X 

* 

21 Output window 


X 


X 

* 

22 Clear display list 


X 


X 

* 

23 Output bit image file 


X 


X 

* 

60 Select pallette 




X 

* 

9 1 I nqu ire pallette film types 




X 

★ 

92 Inquire pallette driver state 




X 

* 

93 Set pallette driver state 




X 

* 

94 Save pallette driver state 




X 


* Not implemented on atari ST 


Scrn = screen 
Plot = plotter 


Prnt - printer 
Mfil - metafile 
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GEM VDI functions continued 


Op 

code 


Definition 

Scrn 

Output device 
Prnt Plot 

Mfil 

5 


Escape codes 





* 

95 

Supress pallette messages 




X 

* 

96 

Pallette error inquire 




X 

* 

98 

Update metafile extents 




X 

* 

99 

Write metafile item 




X 

* 

100 

Change GEM VDI filename 




X 

6 


Polyline 

X 

X 

X 

X 

7 


Polymarker 

X 

X 

X 

X 

8 


Text 

X 

X 

X 

X 

9 


Filled area 

X 

X 

X 

X 

10 


Cell array 

X 

X 

X 

X 

11 

Esc 

Generalized Drawing Primitives 






code 







1 

Bar 

X 

X 

X 

X 


2 

Arc 

X 

X 

X 

X 


3 

Pie 

X 

X 

X 

X 


4 

Circle 

X 

X 

X 

X 


5 

Ellipse 

X 

X 

X 

X 


6 

Elliptical arc 

X 

X 

X 

X 


7 

Elliptical pie 

X 

X 

X 

X 


8 

Rounded rectangle 

X 

X 

X 

X 


9 

Filled rounded rectangle 

X 

X 

X 

X 


10 

Justified graphics text 

X 

X 

X 

X 

12 


Set char height abs. mode 

X 

X 

X 

X 

13 


Set character baseline vector 

X 



X 

14 


Set colour representation 

X 



X 

15 


Set polyline linetype 

X 

X 

X 

X 

16 


Set polyline line width 

X 



X 

17 


Set polyline colour index 

X 

X 

X 

X 

18 


Set polymaker type 

X 

X 

X 

X 

19 


Set polymarker height 

X 



X 

20 


Set polymarker colour index 

X 

X 

X 

X 

21 


Set text face 

X 

X 

X 

X 


* Not implemented on atari ST 


Scm = screen 
Plot - plotter 


Prnt = printer 
Mfil = metafile 
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GEM VDl functions continued 


Op 

code 

Definition 

Scm 

Output device 
Prnt Plot 

Mfil 


22 

Set text colour index 

X 

X 

X 

X 


23 

Set fill interior style 

X 

X 

X 

X 


27 

Inquire cell array 

X 



X 


*28 

Input locator 

X 



X 


*29 

Input valuator, request/sample 

X 



X 


*30 

Input choice, request/ sample 

X 



X 


*31 

Input string 

X 



X 


32 

Set writing mode 

X 

X 


X 


*33 

Set input mode 

X 



X 


35 

Inquire curr polyline attributes 

X 

X 

X 

X 


36 

Inquire curr polymarker attr’s 

X 

X 

X 

X 


37 

Inquire curr fill area attributes 

X 

X 

X 

X 


38 

Inquire curr graphic text attribs 

X 

X 

X 

X 


39 

Set graphic text alignment 

X 

X 

X 

X 


100 

Open virtual screen workstation 

X 





101 

Close virtual screen workstation 

X 





102 

Extended inquire function 

X 

X 

X 

X 


103 

Contour fill 




X 


104 

Set fill perimeter visibility 

X 

X 

X 

X 


105 

Inquire pixel 






106 

Set graph text special effects 

X 

X 


X 


107 

Set char cell ht, pnts mode 

X 

X 

X 

X 


108 

Set polyline and styles 

X 

X 

X 

X 


109 

Copy raster, opaque 

X 





110 

Transform form 

X 





111 

Set mouse form 

X 





112 

Set user-defined fill pattern 

X 

X 


X 


113 

Set user- defined linestyle 

X 



X 


114 

Fill rectangle 

X 



X 


115 

Inquire input mode 

X 





116 

Inquire text extent 

X 

X 

X 



117 

Inquire character cell width 

X 

X 

X 

X 



* Not implemented on atari ST 


Scm = screen 
Plot = plotter 


Prnt = printer 
Mfil = metafile 
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3 

> 

^3 

3 

'3 
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3 
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GEM VDl functions continued 


Op 

code 

Definition 

Scrn 

Output device 
Prnt Plot Mfil 

118 

Exchange timer interrupt vector 

X 



119 

Load fonts 

X 



120 

Unload fonts 

X 



121 

Copy raster, transparent 

X 



122 

Sho w cursor 

X 



123 

Hide cursor 

X 



124 

Sample mouse button state 

X 


X 

125 

Exchange button change vector 

X 



126 

Exch. mouse movement vector 

X 



127 

Exchange cursor change vector 

X 



128 

Sample keyboard state info 

X 



129 

Set clipping rectangle 

X 

X 

X 

130 

Inquire facename and index 

X 

X 

X 

131 

Inquire current face info 

X 

X 

X x 


* Not implemented on atari ST 

Scrn = screen Prnt = printer 

Plot = plotter Mfil = metafile 

The standard range of VDl function output devices include a camera and a tablet as 
well as the screen, printer, plotter and metafile. Only the screen is implemented on 
the Atari ST. 
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GEM AES function calls 


Op 

code Description 


Application library routines 


10 

Initialise application 

APPUNIT 

11 

Read message from pipe 

/APPI READ 

12 

Write message to pipe 

APPI WRITE 

13 

Find another application 

APPL.FI NO 

14 

Playback GEM recording 

APPLTPLAY 

15 

Record GEM session 

APPI TRECORO 

19 

Cleanup and exit 

APPI EXIT 


Timer event routines 


20 

Waiting for keyboard input 

EVNT.KEY 

21 

Waiting for button input 

EVNT.BUTTON 

22 

Waiting for mouse input 

EVNT-MO.USE 

23 

Waiting for messag input 

EVNTJIESAG 

24 

Waiting period 

EVNT-T1MEF 

25 

Waitg for multi-events 

EVNT.MULTI 

26 

Get/set mouse clickrate 

EVNOCLICK 


Menu library routines 


30 T ogg ie ap pi ication menu ba r 

31 T oggle m en u ch eck mark 

32 Toggle menu item able 

33 Toggle display video 

34 Change item menu text 

35 Put acc’s menu in desk 

MENILBAR 

MENIUCHECK 

MENU_I ENABLE 

MENILTNORMAL 

MENLLTEXT 

MENU.REGISTER 


Object library routines 

40 Add object to tree 

OBJ (LADD 


4 1 Delete ob jet from tree 

OBJCLOELETE 


42 Draw an object or tree 

OBJC.DRAW 


43 Find objet under mouse 

OBJC.FIND 


44 Compute object offset 

OBJC.OFFSET 


45 Change obj tree order 

OBJC.ORDER 


46 Edit objects text 

OBJC.EDIT 


47 Change objects state 

OBJ C.C MANGE 
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GEM AES function calls - continued 


) 


J 


Form library routines 


50 

Monitor user/form 

FQRFLDO 

51 

Toggle dialog boxes 

F0RMJ)IAL 

52 

Display alert box 

FORM_ALERT 

53 

Display error box 

F0RH.ERR0R 

54 

Centre dialog box 

F0RfLCENTER 

Graphics library routines 

70 

Draw a rubber box 

GRAF_RUBBERBOX 

71 

Drag a box around 

GRAF.DRAGBDX 

72 

Draw moving box 

GRAF_M0VEB0X 

73 

Draw expanding outline 

GRAF.GROWBOX 

74 

Draw shrinking outline 

GRAF_SHR 1CKB0X 

75 

Test for mouse inside 

GRAF.WATCHBOX 

76 

Slide box in parent 

GRAFTS LI DEBOX 

77 

Return screen handle 

GRAF.HANDLE 

78 

Redefine mouse form 

GRAF„MOUSE 

79 

Return mouse attributes 

GRAFJWSTATE 

Scrap library routines 

80 

Read clipboard directory 

SCRPJEAD 

81 

Write directory to clipboard 

SCRP_WRITE 


File selector routines 


90 

Display file selector box 

FSEI I NPUT 


Window library routines 

100 

Allocate full window 

WIND^CREATE 


101 

Open window to size 

W1ND_0PEN 


102 

Close window 

WINO.CLGSE 


103 

Deallocate window 

WIND_DELETE 


104 

Get window data 

WIND.GET 


105 

Set window data 

WIND-SET 


106 

Find mouse window 

WIND.FIND 


107 

Update window 

WINDJJPDATE 


108 

Calculate window data 

WIND-CALC 
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GEM AES function calls — continued 


Resource library routines 


110 

Load resource file 

RSRC-LOAD 

111 

Deallocate resource file 

RSRC_FREE 

112 

Get structure address 

RSRC.GADDR 

113 

Save structure index 

RSRC.SADDR 

114 

Convert characters to pixels 

RSRC—OBF IX 

Shell library routines 

120 

Find how created 

SHELL_READ 

121 

Exit AES or run other 

SHEU WR I TE 

122 

Get data 


123 

Put data 


124 

Find filename path 

SHELL.FINO 

125 

Find parameter address 

SHELLENVRN 
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Intelligent keyboard (ikbd) command set 


Command 

Code 


Dec 

Hex 

Function 

128 

80 

Reset return keyboard to power-up 

1 

01 

status without affecting clock. 

A break > 200ms also causes a reset 

7 

07 

Set mouse button action 

8 

08 

Set mouse relative position reporting 

9 

09 

Set mouse absolute positioning 

10 

OA 

Set mouse key code mode 

11 

0B 

Set mouse threshold 

12 

OC 

Set mouse scale 

13 

OD 

Interrogate mouse position 

14 

OE 

Load mouse position 

15 

OF 

Set Y = 0 at bottom 

16 

10 

Set Y = 0 at top 

17 

11 

Resume 

18 

12 

Disable mouse 

19 

13 

Pause output 

20 

14 

Set joystick event reporting 

21 

15 

Set joystick interrogation mode 

22 

16 

Joystick interrogation 

23 

17 

Set joystick monitoring 

24 

18 

Set fire button monitoring 

25 

19 

Set joystick keycode mode 

26 

1A 

Disable joysticks 

27 

IB 

Set time of day clock 

28 

1C 

Interrogate time of day dock 

32 

20 

Memory load 

33 

21 

Memory read 

34 

22 

Controller execute 


Status inquiries (OR BOH with command) 

The status of the keyboard can be determined by interrogating the status register in 
the configuration tables. 
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Code 

Dec Hex 

Function 

246 F6 

247 F7 

248 F8 1 
248 F8 

F9 l 
FA 

252 FC ' 

253 FD 

254 FE : 

255 FF : 

Status report 

Absoke mouse position record 
Relative mouse position record 
1 1 1 1 lOxx (xx = right-left button state) 
delta Xj 2’s complement 
delta y, 2 3 s complement 
Timepf day (resolution of 1 second) 

Joystick report header (both sticks) 

xOOOyyyy x= trigger Joystick 0 event 

xOOOyyyy y = stck posn Joystick 1 event 


A-line routines 


Dec 

Hex 1 A y line function 

20480 

20481 

20482 

20483 

20484 

20485 

20486 

20487 

20488 

20489 

20490 

20491 

20492 

20493 

20494 

20495 

A000 Initialization 

A001 Put pixel 

A002 Get pixel 

A003 Line 

A0G4 Horizontal line 

A005 Filled rectangle 

A006 Line-by-line filled polygon 

A007 BitBlt (including half tone source patterns) 

A008 TextBlt (ali 1 6 BitBlt logic operations) 

A009 Show mouse 

AOOA Hide mouse 

AOOB Transform mouse 

AOOC Undraw sprite 

AOOD Draw sprite 

A00E Copy raster form 

AO OF Seedfill 


Appendix F 
Parameter blocks 
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SYSTEM BLOCKS 


System start-up block 


offset 



Branch to reset handler 



$00 

Reseth \ 



502 

Vers 

OS version number 



$04 

Reseth 

System reset handler 



$08 

Os text 

Base of OS 

Pointers 

12 

$0C 

Endos 

End of OS mem used 

16 

$10 

Reseth 

Default shell 


20 

$14 

Magic 

Verification no. or zero 


24 

$18 

Date 

System build date 



Boot sector parameter block 


offset 





$00 

BRA.S 

Branch to boot code 


$02 

OEM's space 

Reserved for OEMs use 


$08 

Vol set # 

24 bit volume serial number 

11 

SOB 

BPS 

Number of bytes/sector 

13 

$0D ! 

SPCs 

Number of sectors/cluster 

14 

S0E 

RES j 

Number of reserved sectors 

16 

S10 

NFATS 

Number of file alocation tables 

17 

$11 

ND1RS 

Number of directory entries 

19 

$13 

NSECTS 

Number of sectors on media 

21 

$15 

MEDIA 

Media descriptor - not used 

22 

$16 

SPF 

Number of sectors/FAT 

24 

$18 

SPT 

Number of sectors /track 

26 

$1A 

NSIDES 

Number of sides on media 

28 

SIC 

NHID 

Number of hidden sectors-not used 

30 

$1E 

boot code 

Start of code* if any ? 

511 

$1FE 

last word 

Used for checksum 

512 

$200 
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DEVICE DRIVERS 

Each device has one driver (Device control block - DCB) that contains entry points 
to routines and constants used by systems to initialize the device's state during a 
warm-start. The routines and constants are defined as follows: 


Device driver 

offset 



500 

BREAD 

Read sector 


$04 

BWRITE 

Write sector 


508 

BINIT 

Initialize drive (warm start) 

12 

$oc 

B FORMAT 

Format drive 

16 

$10 

BINTR 

Vblank call (timeout-homing) 

20 

$14 

BRDTRK 

Read track 

24 

518 

BWRTRK 

Write track 

28 

$IC 

BXLATE 

Logical to physical translate 

32 

$20 

BCVS1Z 

CSV size allocation 

34 

522 

BALVSIZ 

ALV size allocation 

38 

526 

BDEFINFO 

Default info block 

42 

$2A 




Device drivers are stored in RAM in a device state block (DSB), the D SB contains 
TOS specific data structures (the DPB and DPH) and device specific information 
such as the number of tracks^ head seek rate. The DSB is allocated during a warm- 
start. 
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Device state block 


offset 





$00 

DDPH 

Device parameter header 

26 

$1A 

DDPB 

Disk parameter block 

42 

$2 A 

DINFOSIZ 

DSB size (not ind DDPH) 

44 

$2C 

DPHYSDEV 

Device physical number 

46 

$2E 

DNTRACKS 

No. tracks on device 

48 

$30 

!55PT 

No. sectors /track 

50 

$32 

DNSIDES 

No. sides/device 

52 

$34 

DSEEKRT 

Floppy seek rate 

54 

$36 




Floppy parameter block 


offset 



$00 

Flock 

Floppy lock return address 


$04 

Cret 

Callers return address 


108 

Dmapn 

DMA pointer 

12 

$oc 

— 

Obsolete 

16 

$10 

Devno 

Device number 

18 

$12 

Secno 

Sector number 

20 

$14 

Trkno 

Track number 

22 

$16 

Sidno 

Side number 

24 

$18 

Secnt 

Sector count 

26 

$la 




Sector buffer block 


offset 



$00 

BNEXT 

Next buffer or null 


$04 

BBUF 

Size of buffer (512 bytes) 


$08 

BLRU 

LRU replacement value 

12 

$0C 

BFLAGS 

Valid/ dirty flags 

14 

$0E 

BDEV 

Device number 

16 

$10 

BTRACK 

T rack number 

18 

$12 

BSIDK 

Side number 

20 

$14 

BSSECT 

Start sector number 

22 

$16 

BESECT 

End sector number 

24 

$18 

BPSECT 

Physical sector number 

26 

$1A 

BSIZE 
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PROGRAM PARAMETER BLOCKS 


Transient program area block 


offset 


Base 

page 

Text 

Data 

BSS 

Application 
user area 


Low TPA 

To maintain maximum GEM DOS 
compatibility, free unused memory 
and lower top of stack (4 A). 

Determine memory available and allocate 

High TPA 


it. 


Load block 


offset 

$00 


$04 


$08 

12 

$0G 

16 

$10 

20 

$14 

22 

$16 


Opened program file address 
Base address to load program 
Program end address + 1 
Address of base page 
Default user stack pointer 
Loader control flags 
G„load at bottom 
l_load at top (reserved) 


Base page format block 


offset 



$00 

Low TPA 

Base address of TP A 


$04 

Hi TPA 

End of TPA + 1 


$08 

Tbase 

Base address of text 

12 

$oc 

Tien 

Length of text 

16 

$10 

Dbase 

Base address of ink data 

20 

$14 

Dlen 

Length of data 

24 

$18 

Bbase 

Base add of BSS union data 

28 

$1C 

Blen 

Length of BSS uninit data 
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Atari OS specific base page 



Length free memory after BSS 
Drive from which prog loaded 
Reserved by BDOS 
2nd parsed FCB \ Command 
1st parsed FCB ) line 
Command tail and default 
DMA buffer 

$FF end 


Set 

by 

CCP 


GEMDOS specific base page 


offset 




32 

820 


DTA address pointer 

36 

$24 


Parent’s base page pointer 

40 

$28 


Reserved 

44 

82C 

Environ 

Environment string pointer 

128 

$80 

Cmdline 

Command line image 


File header 

offset 

601 AH data & BSS contiguous 
else 601BH (not supported by ST OS) 
Bytes in text segment 
Bytes in data segment 
Bytes in BSS 
Bytes in symbol table 
Zero (reserved) 

Start of text seg & prog exec 
Zero if no relocation bits 



m 


$02 


$06 

10 

$0A 

14 

80E 

18 

$12 

22 

$16 

26 

$1A 


BRA.S flag 


Extension to file header if BSS and data not contiguous: 
(not supported by ST OS) 

offset 
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28 

$1C 


Start address of data segment 

32 

$20 


Start address of BSS 

36 

$24 




Memory parameter block 



Owner description 
No. bytes in block 
Start address of block 
Next link MD 
Roving pointer 
Memory allocation list 
Memory free list 


Memory 

descriptor 
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GEM PARAMETER BLOCKS 


VDI parameter block 


offset 


$00 

contrl 

$04 

in tin 

$08 

ptsin 

12 $0C 

intout 

16 $10 

ptsout 

20 $14 

_ 


Longword address 

Control table pointer 
input attribute table pointer 
input points table pointer 
output attribute table pointer 
output points table pointer 


VDI control table 


offset 



$00 


$02 


$04 


$06 


$08 

10 

$0A 

12 

$oc 

14 

$0E 


Op code 
~Lptsin 
Lptsout 
Lin tin 
Lintout 


Longword address 

Function op code 
input coordinate \ Size in 
output coordinate! Wordpairs 
input attribute \ Size in 
output attribute 1 words 
Subfunction ident number 
Device handle 

Op code dependent information 


Longword address 


AES parameter block 


offset 


$00 

control 

$04 

global 

$08 

i nt_i n 

12 $0C 

irt.out 

16 $10 

addr_in 

20 $14 

addr_out 

24 $18 



Control table pointer 
Global array pointer 
input attribute table pointer 
input points tabic pointer 
output attribute table pointer 
output points table pointer 


Table 

sizes 
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AES control table 



offset 

m 
$02 
$04 
$06 
$08 
10 $0A 


Op code. 


■Lint- in 


-ml nut 


I flrirtr ,,iJL 


l a Ml nul 


Function op code 
input coordinate j 
output coordinate i 
input attribute * Size in 
output attribute * longwords 


Size in 
words 


Tabic 

Sizes 


■ I 


■ n 


AES global array 


offset 

$00 
$02 
$04 
$06 
10 $0A 

14 S0E 
18 $12 
22 $16 
26 $1A 

30 $1E 


vi-rsnin- 


-CfiliaL. 


jsL 


private. 


prrec 


reserved. 


served 


reserved 


jeaeasd 


GEM AES version ident word 

Max Concurrent applies allowed 

Unique application identifier 

Longword user data 

Resource address tree pointer 

Zero 

Zero 

Zero 

Zero 


«. > 
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A-LINE VARIABLES 


A-line routine table 

offset 

Function 



$00 

0 Number of video planes i Can produce special 


802 

2 Number of by tea/ video line > effects. 


$04 

4 Pointer to Cntrl array 


808 

s Pointer to I ntin array 


80 C 

12 Pointer to Ptsin array 


810 

16 Pointer to.lntout array 


814 

20 Pointer to Ptsout array 


$18 

24 Bit plane 0 

current 


81A 

26 Bit plane l 

i color 


SIC 

28 Bit plane 2 

value 


81E 

30 Bit plane 3 , 



$20 

32 ^1 



822 

34 VD I line style equivalent 


824 

36 Writing mode: 0 - replace; 1 = transparent 




2 = XOR mode 3 = inverse transparent 


$26 

38 XI coordinate 


828 

40 Y1 coordinate 


$2A 

42 X2 coordinate 


$2C 

44 Y2 coordinate 


$2E 

46 Pointer to current fill pattern 


$32 

50 Fill pattern 

mask 


$34 

52 Mu hi- plane fill pattern 



CLcurrent fill pattern is single plane 



836 54 

838 56 

$3 A 58 

83C 60 

S3E 62 

840 64 

842 66 

$44 68 

846 70 


848 72 

84A 74 

84C '76 


l_current fill pattern is multi-plane 
Clipping flag: 0 = no dipping 
Minimum x clipping value 
Minimum y dipping value 
Maximum x clipping value 
Maximum y dipping value 
Accumulator for textblt x dda 
initialize to 8000H before each call 
Textblt scale factor 
Scale direction CLdown 
Font status 

1 = current font monospaced & may be thickened 
0 = may not be thickened to increase font width 
X coor of character in font form 
Y coor of character in font form (typically 0) 

X coor of character on screen 


Continued . . 
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S4E 

78 

Y coor of character on screen 

$50 

SO 

Character width 

$52 

82 

Character height 

$54 

84 

Pointer to start of font data (font form) 

858 

88 

Width of font form 

85A 

90 

Style bit: 0 = Thicken, bit 1 = lighten, bit 2 = skew 
bit 3 = underline (ignored), bit 4 — outline 

$5C 

92 

Lighten text mask 

$5E 

94 

Skew text mask 

$60 

96 

Text thickening additional width 

$62 

98 

Offset above character baseline for skew 

864 

100 

Offset below character baseline for skew 

$66 

102 

Scaling flag: 0 = no scaling 

$68 

104 

Character rotation vector 
0 — horizontal 
900 = vert down, etc 

$74 

116 

Copy raster form type flag (RAM VD1 only) 

0 = opaque type 

n-plane source to n -plane destination bitblt write mode 
<>0_transparent type 

1 -plane source to n-plane destination VD1 write mode 

$76 

118 

Abort fill routine pointer 


f not available on disk based versions of TOS ) 


The A-line variable table contains other parameters 
which may be of use to the programmer. 


offset Function 


8D2 

-46 

Pixel ceil height. (Same as font form’s height) 

$D4 

-44 

Maximum number of cells across -1 (X) 

SD6 

-42 

Maximum number of cells high -1 (Y) 

SD8 

-40 

Byte offset next vert cell. Sen wid(byte) * Pixel cell ht 

8DA 

-38 

Physical color index of background color. 

$DC 

-36 

Physical color index of foreground color. 

8DE 

-34 

Current cursor address 

8E2 

-30 

Byte offset from screen base to top of first cell 

SE4 

-28 

Cursor position: cell x 

8E6 

-26 

Cursor position: ceil y 

8E8 

-24 

Cursor flash interval (in frames) 


Continued . . . 
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$E9 

-23 

Cursor countdown timer 

SEA 

“22 

Address of monospace font data 

Each cell is 8 pixels wide and byte aligned. 

The data format is defined in the VDI manual. 
The cells may be arbitrarily high. 

SEE 

-18 

Last ascii code in font 

SFO 

-16 

First ascii code in font 

SF2 

-14 

Width of font form in bytes 

$F4 

-12 

Maximum x pixel value 

SF6 

“10 

Address of font offset table (per VDI spec) 

SFA 

-06 

Alpha text status byte 

bit 0 cursor flash 0 — disabled, 1 — enabled 

bit 1 flash state 0 = off, 1 = on 

bit 2 cursor visibility 0 = invisible, 1 = visible 

bit 3 end of line 0 = overwrite, 1 = wrap 

bit 4 reverse video 0 — on, 1 = off 

bit 5 cursor position saved 0 = false, 1 — true 

SFC 

-04 

Maximum y pixel value of the screen 
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Sprite definition block 


offset 



$00 


X offset of hot-spot 



$02 


Y offset of hot-spot 



504 


Format flag 



$06 


Background i Color 



$08 


Foreground * table index 


10 

S0A 


Interleaved i 

j fcfgnd line 0 

12 

50C 


background/foreground 

l F’gnd line 0 

74 

54A 


image (32 words) 

| F’gnd line 16 

76 

$4C 





Format flag 


+ ve 
Fg Bg 

-we 

Fg Bg 

color 

plotted 

O 0 

0 0 

Transparent 

0 1 

0 1 

Background 

1 1 

1 1 

Foreground 

1 o 


Foreground 


1 0 

XOR screen 


Memory form definition block (MFDB) 

offset 


12 

16 

20 

24 

28 

32 

36 


$00 

$04 

$08 

$0C 

$10 

$14 

$18 

$1C 

$20 

$24 


Mem pointer 


Width 


Height 


Word width 


Format flag 


Mem planes 


32-bit address of pixel 0,0 

( Raster area 
dimensions 
Pixel width/word size 
1 = standard, 0 = device specific 
No- planes in raster area 

! Three 
reserved 
words 
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HEADER BLOCKS 


Cartridge header block 


offset 

Prefix to application header 

252 8FC j 

Flag #$ABCDEF42 program/data 

| 

or #SFA52255F diagnostic 


Application header block 

offset 

Link to next application 
Pointer to initialize code 
or mn flag (MSB) 

Pointer to run code 
DOS-format 1 Time /Date 
DOS-format * application created 
Application size 

Application name (NNNNNNNN . BEE) 


12 

14 

16 

20 


$00 

$04 

$08 

$0C 

$QE 

$10 

$14 


Next 


Flag/inlt 


Run 


Time 


Date 


Size 


Name 



Run flag bn set: 

Bit 0 Run before interrupt vectors and memory initialized 
Bit 1 Run before GEMDOS initialized 

Bit 2 unused 

Bit 3 Run before disk boot 

Bit 4 unused 

Bit 5 Application is a desk accessory 

Bit 6 Not a GEM application. No AES calls 

Bit 7 Requires command line parameters before execution 


E = 3 

— a 


* 

i 

" 3 



Appendix G - MC68000 
Instruction summary 
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ADDRESS MODE 


Assembler language and BASIC equivalents 


Address mode 

Source 

Destination 

Data register 
direct 

Dn MQVE.L D2.D0 
LET D0=D2 

HOVE. L #999.00 
LET 00=999 

Address register 
direct 

An MOVE. LAO, 00 
LET D0-A0 

MOVE A . L #9 9 9 . A0 
LET AO-999 

Address register 
indirect 

(An) MOVE . L (AO). 00 

LET DO,PEEK_L(AO) 

MOVE . L #999 , (A0) 
P0KEJ. (A0) , 999 

Address register 
indirect with 
postincrement 

(An) + MOVE. L (AO) ♦ , DO 
LET 00, PEEK. L( AO) 
LETA0-A0 * 4 

MOVE. L #999, (A0) f 
PGKEJ. (A0) ,999 
LET AQ=AQ + 4 

Address register 
indirect with 
predecrement 

-(An) MOVE . L -(A0). 00 
LET AO* A0 -4 
LET DO, PEEK_L(A0) 

MOVE. L #999 , -(A0) 
LETA0-A0 -4 
P0KE_L (A0). 99 9 

Address register 
indirect with 
displacement 

d(An) MOVE. L 9 ( A0 ) . DO 

LET D0*PEEK_L(9 * A0) 

MOVE . L #999 . 9 (A0) 
P0KE_L( AO+9) , 999 

Address register 
indirect with 
index 

d(An.Ri)M0VE.L9(A0.D2) , DO 

LET D0=PEEK_L(9 + A0*D2) 

MOVE. L #999. 9 (AO. DO) 
POKE_L(AO+9-*DO) . 999 

Absolute short 

ABS.S 

Sxxxx MOVE. L 1024, DO 

LET DO=PEEK_L(1024) 

MOVE . L #999 .1024 
P0KE_L(1024) ,999 

Absolute long 

ABS.L 

Sxxxxxx MOVE. L 1 63840.00 

LET D0-PEEK_L(163840) 

MOVE. L #999 . 1 63840 
PQKE_L( 163840) .999 

Program counter 
with 

displacement 

d(PC) MOVE . L 9 ( PC) ,00 

LET 00=9 + cunts of 
Program Counter 

Not legal 

Program counter 

with 

index 

d(FC. Ri)MQV E . L 9 ( PC . D2 ) P DO 

LET D0=9 + D2 + com of 
Program Counter 

Not legal 
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ALLOWABLE ADDRESS MODE TYPES 



All 

Alt 

Mem 

Add 

Data 

Alfble 

Addr’g 

All 

Add 

Mod 

Dat 

Add 

Mdl 

Dai 

Add 

Md2 

Con 

Add 

Mdl 

Con 

Alt 

Add 

Con 

Add 

Md2 



Source 

Dest. 

Destination 

Dest. 

Source 

Dest . 


Dest. 

Src. 

Dn 

X 


X 

X 

X 

X 

X 




An 

X 




X 






(An) 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

(An) + 

X 

X 

X 

X 

X 

X 

X 



X 

-(An) 

X 

X 

X 

X 

X 

X 

X 


X 


d(An) 

X 

X 

X 

X 

X 

X 

X 

X 

X 

X 

d(An,Ri) x 

X 

X 

X 

X 

X 

X 

X 

X 

X 

ABS sh’t x 

X 

X 

X 

X 

X 

X 

X 

X 

X 

ABS Ig x 

X 

X 

X 

X 

X 

X 

X 

X 

X 

d(PC) 

X 





X 

X 

X 


X 

d(PCRi) x 





X 

X 

X 


X 

Imm 

X 





X 






ADD 

ADD 

ADDl 

NBCD 

ADDQ 

AND 

BTST 

JMP 

MOVEM 

MOVEM 


ADDA 

AND 

ANDt 

NEG 

SUBQ 

CHK 


JSR 

rc£ 

mem 


CMP 

OR 

BCHG 

NEGX 


DIVS 


LEA 

to 

to 


CMPA 

SUB 

BCLR 

NOT 


D1VU 


PEA 

mem 

reg 


MOVE 


BSET 

ORI 








MOVEA 

ASL 

CLR 



MOVE 






SUB 

ASR 

CMP] 

See 


to CCR 






SOBA 

ROXL 

EOR 



MOVE 






ROXR 

EORl 

SUBI 


to SR 







ROL 

MOVE 

TAS 









R OR 


1ST | 


MULS 







LSL 

MOVE 



MULU 







LSR 

fr SR 



OR 

_L 







Alt — Alterable Mod — Mode Mdl = Model /Types of addressing mode 

Mem = Memory Dat = Data Md2 = Mode2 / definitions used by 


Add = Address Con — Control 


\ Motorola to describe 
'allowable modes 


Address inodes 


ENCODING 

The range of addressing modes are coded consistently throughout the MC68000 
instruction set and may be summarized as follows: 


/table 


Addressing 

mode 

Syntax 

Mode 

No. 

Reg 

No. 

Ext. 

words 

Data register direct 

Dn 

0 

n 

0 

Address register direct 

An 

1 

n 

0 

Address register indirect 

(An) 

2 

n 

0 

Address register indirect 
with postincrement 

(An) + 

3 

n 

0 

Address register indirect 
with predecrement 

-(An) 

4 

n 

0 

Address register indirect 
with displacement 

d(An) 

5 

n 

1 

Address register indirect 
with index 

d(An.Ri) 

6 

n 

1 

Absolute short ABS.S 

$xxxx 

7 

0 

I 

Absolute long ABS.L 

$xxxxxx 

7 

1 

2 

Program counter with 
displacement 

d(PC) 

7 

2 

1 

Program counter with 
index 

d(PC.Ri) 

7 

3 

1 

Immediate 

#$xxx 

7 

4 

lor 2 


n — Register number 0 to 7 

Ext. Word - Number of extension words following the op word due to this address 
mode (source and destination ext. words are cumulative) 

Mode No. = Dmod and Smod in instruction code tables 


Reg No. = Dreg and Sreg in instruction code tables 


Assembler language and BASIC equivalents continued 


Address mode 

Source 

Destination 

Immediate #Sxxx 

MOVE. L #65636, DO 

Not legal 

I mm 

LET DO=66536 



Register DO is used 

The source is defined 


for the destination 

as immediate data 

Notes 

as an example; any 

value 999; any other 


other valid effective 

valid effective 


address may be used. 

address may be used. 


Ail equivalents have been defined as having longword operands, byte and word- 
sized operands may also be used. 
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Data storage 


The MC68000 accesses two internal locations for storage; 

Internal registers, of which there are 17, store the data inside the microprocessor 
itself. They are very limited in the amount of data they can store* but provide 
extremely fast access. 


ST RAMI ROM , where data access is still quick, but not as fast as the internal 
register data access. 



— External 
data storage 
(Hard /floppy 
disk) 


ATARI ST 
computer 


Internal memory 
devices 


MC68000 processor 
internal register layout 
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Data types 

The MC68000 microprocessor supports five different data types; some instructions 
are limited to a specific data type, bust mostly there is an allowable range with the 
default of word. Where the choice is not implicit, it is defined in the instruction word 
extension as either yte y word or longword ♦ 

Byte, Word and Longword data types 


MSB 


Word 


31 


23 


High order byte 


25 


Low order byte 
7 0 


Byte 


Hi mid order byte 

High Byte Lomid order byte 

“ “ “ 1 Longword " 


Low byte 


MSB 


BCD and IT data types 


MSB 

Bit data 

LSB 

rum 

4 

TTTT7 

T| 



* 

v 1 




BCD 0 


BCD 1 


Most significant 
BCD byte 


Least significant 
BCD byte 
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Internal registers 

The Motorola 68000 has seventeen 32-bit registers, a 24-bit program counter and a 
16-bit status register, eight of the 32-registers (DO to D7) are used as data 
registersfor operations involving single-bit, bed (4-bit), byte (8-bit), word (16-bit) 
and longword (32-bbit) data. The remaining nine registers are split into two; seven 
of these (AO to A6) act as address registers, and two act as stack pointers. Only one 
stack pointer may be accessed at a ti,me, hence the convention of calling nth A7 . 1 he 
address register operations are based on word and longwords only. 


Data registers 

Data storage of byte, word and longword is always performed in the part of the data 
registers shown; unused parts of the register are not altered. 

Eight 

data 

registers 


31 16 IB 8 7 0 







byte 





word 




Longword 








DO 

D1 

D2 

D3 

D4 

D5 

D6 

D7 


Address registers 

The address registers are used as pointers to user stacks, as base address registers 
and temporary storage for computed addresses tyhat are not to affect the Status 
Register. Address storage is always performed in the part of the address registers 
shown. When used as a destination operand, the entire address is changed regardless 
of the operation size. Address registers do not support byte-sized operations as either 
a source or destination. Words arc sign-extended to longwords before an operation 
is performed. 

Seven 

address 

registers 


AO 
A1 
A2 
A3 
A4 
A 5 
AG 


31 1 6 1 5 8 7 0 









word 


! . 

l 

.ongword 
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U 

3 

3 

3 

3 

3 

3 

r 

3 

3 

1 


Stack Pointer 

The user stack pointer typically saves subroutine returns when in user mode. The 
supervisor stack pointer saves the status register contents during trap and interrupt 
routines as well as the supervisor subroutine returns. Only one of the stack pointers 
is addressable at a time, so they are both called A7. ytes pushed on a stack are stored 
in the high order half of a word. 

Two Stack 
Pointers 

31 0 

User Stack Pointer A 

Supervisor stack Pointer 7 


Program Counter 

The program counter provides the MC68000 with an address range of 16 
Megabytes. As instructions arc based on word-sized operands, the counter must 
always hold an even address. Attempts to address odd-numered locations will cause 
an error trap. 

31 23 ____ 0 

000000 


Status Register 

15 8 7 0 


The status register is split into user and system bytes. The user byte is evaluated for 
the condition codes used in the branching instructions. The codes are affected by all 
instructions that alter the contents of the data registers or memory, but not by 
changes to the address registers. 


USER BYTE 
Condition codes 


i 

jX 

X 

X 

4 

3 

2 

f 

0 


Not used 


Xf 

c 

ju 

w 

> 

ft 

cc 

Zero 

£ 

o 

f 

u 

Carry 

W 



> 



o 



i 
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The unused bits in the status register are read as zero. They are available for the 
MC68000 instruction set. 



SYSTEM BYTE 


15 

X 

13 

X 

X 

10 

9 

8 


Trace 

mode 


Interrupt 

mask 


Supervisor 

state 


Organisation of addresses in memory 


Byte 


Longword 


Word 


Memory 

top 


Byte 


Low byte 


High byte 


Low byte 
High byte 


any 

address 


+ 3 
+ 2 
+ 1 


Even 

address 


+ 1 


Even 

address 


For word and longword 
memory operations* the high 
byte is on a word boundary 
(even address)* the following 
bytes are in order higher in 
memory. 

By convention, system stacks 
grow downwards in memory. 



0 


Memory bottom 
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INSTRUCTION SUMMARY 

Each Motorola MC68000 instruction is presented, many in terms of equivalent 
BASIC Instructions or assembler routines. The similes are for clarification of the 
use of each instruction; there is no access to the data or address registers (Dn or An 
respectively) or the condition codes from BASIC and therefore the examples which 
make use of these registers, and most of the effective address modes (ea), cannot be 
taken literally. 

Key 

&& bitwise AND 
a a bitwise EOR 
| | bitwise OR 


ABCD: Add Binary Coded Decimal with Extend 

Add two byte-sized binary coded decimal numbers and the Extend bit; a dollar sign 
is used to indicate a BCD number. Clear the extend bit and set the zero bit before 
performing this instruction which is limited to byte-size data register operations; 
multibyte additions are performed more easily in memory. 


BCD addition 


DATA Register 


Memory 



Addition 

Multibyte Addition 



Byte only 

MOVE 

#4 ,CCR 

$7 

$27 


ABCD 

-(AO).-(AI) 

ABCD $6 ABCD SI 6 

ABCD DO , D1 

ABCD 

-(AO).-(AI) 

$13 

S43 


ABCD 

-{AQ).-(AI) 


Note that the z-flag is cleared if the result is non- zero* otherwise it is unchanged and 
that in memory additions the data must be stored with the most significant digit 
lower in memory and the address pointers initially set to the byte above the low 
order BCD digit in memory* as the only available addressing mode is predecrement. 


ADD: Add two integers. 

One of the integers must be the contents of a data register. 

LET Dn=Dn + ea ADD ea.Dn 

LET ea-ea + Dn ADD Dn.ea 

Use ADD ea,Dn where the destination is a data register. 

Use ADDA where the destination is an address register. 

Use ADD I or ADDQ where the source is immediate data. 
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Instruction sum mary - continued 

ADDA: Add the contents of the effective address to the contents of the destination 
address register. 

LET An -An + ea A0DA ea ' An 


ADDI: Add a constant value to the contents of the destination effective address. Use 
ADDQ for speed and small integers. 

LET ea=ea + 999 AD0T P"> ea 


ADDQ: Add a constant in the range of 1 to 8 to the contents of the effective address. 
Faster addition than ADDI. 

LET ea=ea + 8 ADDQ # 8ea 


ADDX: Add either register to register, or predecremented memory to memory, 
with extend. Use of the extend bit enables mnltiprecision arithmetic to be 
performed, the extend bit acting as a carry between successive operations. 


Memory additions 

ADDX - (Ay) . - (Ax) 

Where X infers the Extend bit 
LET Ay-Ay-4 
LET Ax-Ax-4 

POKE (Ax ) , PEEK (Ax ) * PEEK(Ay) • X 


Data register addition 
Add two 64 bit integers 

D0.D1 and D2_D3 Lo-Hi resply 
ADD. L 00, D 2 Low bits 
ADDX. L D1 ,03 High bits 

Memory addition 

HOVE #4, OCR 
ADDX, L -(AO) , - (AT ) 

ADDX . L -(A0),-(A1) etc. 


Note that the z-flag is cleared if the result is non-zero, otherwise it is unchanged. 
For memory additions first clear the Extend bit and set the Zero flag. The data must 
be stored with the most significant digit lower in memory and the address pointers 
initially set the operand size above the low order digit in as the only addressing mode 
is predecrement. 
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Instruction summary - continued 


AND; AND the source operand to the destination operand. 

The source AND data is normally used either (a) as a mask enabling a portion of the 
destination operand to be examined (bits are masked by Ts in the source); or (b) to 
clear bits by setting the corresponding bit in the source to a zero. 

LET ea-Dn && ea AND On. ea 

LET Dn^src && On AND ea.On 

If src = 3, then AND sre keeps bits 0 and 1 in Dn only, the others are set to zero. 

Use AND ea,Dn where the destination is a data register. 

Use ANDA where the destination is an address register. 

Use AND I where the source is immediate data. 


ANDI: AND! the immediate data to the destination effective address. 

LET ea-dats && ea ANDI.W #512. DO 

Keep bit 9 of word only 


ANDI to CCR: ANDI the data to the condition code register. 

LET CCR=26 m CCR ANDI #26, CCR 

Normally bits can be tested via the condition codes without using the AND function 
as a mask. Here it is used to zero a bit position where there is a zero in the AND data; 
that is zero and carry (bits 0 and 2 in the CCR) are cleared. 


ANDI to SR; ANDI the data to the status register. 

This is a privileged instruction and attempted access while in user mode will trap to 
the privilege violation exception vector. 

LET 5R=63743 U SR ANDI #63743, SR 

Set the interrupt mask level to zero and leave unchanged the condition code and 
system flags. 
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Instruction summary - continued 

ASL; Arithmetically Shift Left the bits of the operand. 

The last MSB shifted sets the carry and extend bits; the LSB is set to zero each shift. 
The overflow bit is set if the sign is changed during the shift and is used to flag a 
change of sign. The instruction is used for fast multiplication of * 2 and x 4; other 
values should use MULS. 



LET ea=ea * 2 
LET Dy=Dy * (2aDx) 
LET Dy-Dy # (2a6) 


ASL ea (shift 1) 

ASL Dx , Dy (reg modulo 64) 
ASL #b.Dy (shift 1 to 8) 


ASRt Arithmetically Shift Right the bits of the operand. 

The MSB sign bit is retained; the last LSB shifted is used to set the carry and ex ten 
bits. This instruction can be used for rapid integer division by 2, 4, S ot signed 
numbers; use DIVS for other divisions. 


sign bit — 


LET ea-INT(ea/2) ASR ea ( shlift ^ 

LET Dy=INT<Dy/(2ADx) ASR Dx - D V < re 9 " l0dul ° e4 > 

LET Dy-INT{Dy/(2A5> ASR < shift 1 t0 


Bcc: Branch on condition a two’s complement displacement from the current 
program counter position (Instruction address + 2) + 126 to -128 for a short branch 
or + 32766 to -32768 for a word branch operation, the condition xx may be: 


2 3 s complement 
arithmetic 


GT Greater Than 
LT Less Than 
GE Greater Than 
or Equal to 


BEQ #14 
BGT label 


EQ 

Equal To 

CS 

Carry Set 

NE 

Not Equal 

cc 

Carry Clear 

MI 

Minus 

vs 

Overflow 

PL 

Plus 

VC 

No Overflow 

HI 

Higher Than 

LE 

Less Than or 

LS 

Lo wer Than or same 


Equal to 


IF Dn = 0 THEN GOTO yy 
IF Dn > 0 THEN GOTO label 
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& 2 3 

'■* 2 3 

S’ h 

Si 1 3 


z: = 3 

V ■ 

fe g 3 

k: = 3 
E | 3 
E g 3 

Hi M D 

I 

I s „ 

.E 

A* 

X 

:i; 

■ I 

= 1 


Instruction summary - continued 
BCHG: A bit is tested and its state reversed. 

If the bit was zero before the test; that is dear, then the Zero flag is set, otherwise it 
is cleared. 


IE BITn - 0 THEN set_Zf lag: 
ELSE clear^Zflag 
LET BITn = 1 BITn 


BCHG #6 , ea (data modulo 3) 
BCHG Dn.ea (reg «modu 1 o 32) 


BCLR: A bit is tested and then cleared. If the bit was zero before the test; that is 
clear, then the Zero flag is set, otherwise it is cleared. 


IF BITn - 0 THEN set_ZFlag: 
ELSE clear^Zf lag 
LET BITn * 0 


BCLR #6,ea (data modulo 8) 
BCLR Dn,ea (reg modulo 32) 


BRA: B Ranch Always. 

A two's complement displacement branch either of + 126 to -128 bytes by a single 
word instruction or of + 32766 to -32768 bytes by a two- word instruction from the 
current program counter position (instruction address + 2). 


GOTO label 
GOTO 1275 


BRA label 
BRA #3 


BSET: A bit is tested and then set. 

If the bit was zero before the test; that is clear, then the Zero flag is set, otherwise it 
is cleared. 


IF BITn - 0 THEN set_Zflag: 
ELSE c 1 ea r_Zf 1 ag 

LET B ITn= 1 


BSET #6. ea (data modulo 8) 
BSET Dn,ea (reg modulo 32) 


BSR: Branch to SubRoutine. 

Either a two's complement displacement of +126 to -128 bytes by a single-word 
instruction, or of + 32766 to -32768 bytes by a two- word instruction, from the 
current program counter position (instruction address +2). Return to the next 
instruction via an RTS from the subroutine. 


GOSUB label 
GOSUB 1276 


BSR label 
BSR #8 
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Instruction summary - continued 

BTST: A bit is tested. If the bit was zero; that is clear, then the Zero flag is set, 
otherwise the Zero flag is cleared. 

IF BITn - 0 THEN set_Zflag: BTST #6,ea (data modulo 8) 

ELSE clear_Zf lag BIST Dn r ea ( reg modulo 32} 


CHK: Check a data register low-order word against the two’s complement upper 
bound of the source operand. 

If the register value is less than zero or greater than the test value, then jump to the 
CHK Trap exception vector, 

IF Dn > ea OR CHK ea.On 

Dn < 0 THEN GOSUB chk_trap 


GLR: Clear an operand sets all or part of a specified address or register to zero. 

LET ea=0 CLR ea 

MOVEQ #0,Dn is quicker than CLR.L Dn 
SUBA.L An,An is quicker for memory applications 


CMP: The compare instructions are used exclusively to set the condition code 
registers for a subsequent conditional operation. The comparison is made by 
subtracting the source operand from the destination operand and setting the 
condition codes accordingly; neither operand is altered by the instruction. 

CMP ea.On 

IF ea-Dn THEN GOTO loop BEQ loop 

Use CMPA when the destination is an address register. 

Use CMP! when the source is immediate data. 

Use CMPM for memory to memory comparisons. 


CMPA: Subtract the source operand from the address register and set the condition 
code flags accordingly. 

The comparison is based on a sign-extended source if it is a word operand. The 
address register is not altered. 
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3 

=3 

3 

3 


3 

3 

3 

3 

3 
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Instruction summary - con tinued 

CMPI: Subtract the immediate operand from the effective address operand and set 
the condition code flags accordingly. 

Neither operand is altered. Use TST for comparing with zero as it is much quicker. 

CMPI #999. ea 


CMPM: Subtract the contents of the memory address pointed to by the source 
address register from the contents of the memory address pointed to by the 
destination register and set the condition code flags accordingly. Increase the value 
of both address registers by the size of the operand (1, 2 or 4 byte word and 
longword respectively)* 

The main use for this instruction is comparing strings 


LET Dn 3 lengt lustring -1 
loop 

IF PEEK (Ay) <> PEEK (Ax) THEN 
Ay =* Ay + s : Ax * Ax * $ 
GOTO not_saaie 
ELSE 

Ay - Ay + s:Ax - Ax + s 
LET Dn - Dn -1 
IF Dn ■ -1 THEN GOTO next 
GOTO loop 
END IF 
next 


loop 

CMPM (Ay)*. (Ax) 
BNE nat_same 
DBRA Dn.loop 

next 


noiusame 



not_same 

s - operand size 


Dn is the 
character count 


3P 

3 

3 

3 

1 

3 


DBcc: Test the condition and exit loop to the next instruction if the condition is 
met. 

If the condition is not met, then decrement the low order 16 bits of the count data 
register. If the count becomes -1, then exit loop and carry on with the next 
instruction, otherwise branch the two's complement displacement of the following 
word -32766 to + 32768 from the current program counter position (Instruction 
address + 2)* The test may be one of the following: 
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Instruction summary - continued 


EQ Equal To 

NE Not Equal 

MI Minus 

PL Plus 

HI Higher than 

LS Lower than or same 


CS Carry Set 
CC Carry Clear 
VS Overflow 
VC No Overflow 
T True 
F False 


2*s complement 
arithmetic 


GT Greater than 
LT Less than 
GE Greater than 

or Equal to 
LE Less than or 

Equal to 


DBEQ DO, loop 

(Equivalent) 


BEQ pass 
SUB #1 .DO 
BPL loop 


pass 


DBT: Always branches and is of little use. 


_ 'trm HRF it makes the branch based on the data register 

DBRA: Sometimes written DBF, it Therefore the count should be 

count only and branches when t e “ u ^ r . , g emercd via a j ump or branch at the 

““ ““ 0,ef " ,l!, “ “““ 

count will cause an immediate exit from the loop. 


DIVS: Sign Divide .32-bit ^ iS 5 «»- 

r tSTS 1 " 1 * nppet. .6 ^ 

16 ** - *•* - « md ■“ 

operation terminated without affecting either operand. 


LET Dn=Dn / ea 


D 1 VS ea.Dn 


ASR 


ea 


MOVED #2.02 
ASH D2,Dx 


is a fast signed divide by two. 


is a quicker divide by four. 


rMT 7 c a niVTI for division by a prime number, otherwise think ot 

— :rsi“ . « — — ■ —* is - *“■ 
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Instruction summary - continued 


DIVU: Unsigned arithmetic divide of a 32-bit data register destination operand by a 
16-bit source operand. 

The integer result is stored in the lower 16 bits of the destination register and the 
remainder in the upper 16 bits. Division by zero causes a iump to the Divide- By- 
Zero exception vector. On overflow' the result is larger than 16 bits, the V-flag is set 
and the operation terminated without affecting either operand. 


LET Dn-On / ea 


DIVU ea.Dn 


EOR: EOR the data register source operand to the contents of the destination 
operand. 

The source EOR data is normally used to invert the state of a bit or bits. 

LET ea-Qn aa ea EOR Dn.ea 

If Dn = 3, then bits 0 and 1 in the effective address are inverted. 

Use EORI where the source is immediate data. There is no memory to data register 
operation. 

EORI: EORI die immediate data to the destination effective address. 

LET ea^data aa ea EOR LB # 16 , DO 

Invert bit 4 of DO 

EORI to CCR: EORI the immediate data to the condition code register. 

LET CCRM aa CCR EORI # 4 . CCR 

Toggle the Zero_flag 


EORI to SR: EORI the immediate data to the status register. 

This is a privileged instruction and attempted access while in user mode will cause a 
trap to the privilege violation exception vector. 


LET SR =8192 aa SR 


EORI # 81 92 , SR 
Toggle the supervisor bit 
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Instruction summary - continued 

EXG; Exchange the longword contents of two registers. 

Referred to in many BASICs as SWAP, which has a different meaning in the 
MC68000 instruction code. 

LET tmp=D0 : D0=D1 EXG D0.D1 
LET tmp=AO:A0=A1 :A1-tmp EXG AO , A1 

LET tmp=D0:00=A0: AO^tmp EXG DO, AO 


EXT: Sign-extend a data register contents, a byte to a word or a word to a longword, 
to permit operations involving mixed size data to take place. 

EXT Dn 


ILLEGAL: The illegal instruction causes the processor to jump to the illegal 
instruction trap exception process subroutine. 

GOSUB 111 _Trap ILLEGAL 


JMP and JSR: JMP and JSR are long forms of BRA and RSR. 

The main difference lies in the jump instruction^ ability to access any part of 
memory whereas the branch instructions are limited to a relative ± 32K bytes jump. 


JMP: Jump to a routine in memory specified by the effective address, either 
absolute or relative to the current program counter position, 

GOTO ea . JMP ea 


JSR: Jump to a subroutine in memory specified by the effective address , either 
absolute or relative to the current program counter position 

GOSUB ea JSR ea 


LEA: Load Effective Address loads a calculated effective address into an address 
register. 

The calculated address can be the sum of two registers, one must be an address 
register, and a displacement which provides the addition of two registers and a 
displacement without affecting either register, all in a single instruction. 

Let An a Start_of_text address LEA text, An 

Let An*Start_of stable LEA tabl ,An 

GOTO An + DO JMP O(An.DO) 


LET A0=A1 ♦ D2 *64 


LEA 64 (A1 .02) ,AQ 


Instruction summary - continued 


LINK; LINK enables a block of memory, part of the stack, to be temporarily 
reserved for a specific purpose; that is an index table, a text string, an array etc. and 
the space recovered when the requirement has passed. 

DIM A(64) LINK An,# 64 

Saves a block of 64 bytes in memory. 

The original value of An is preserved on the stack and will be recovered on UNLK. 
The current value of An is the start of the data space which may be most easily 
accessed via indirect with displacement or indirect with index addressing modes. 


LSL: Logically Shift Left the bits of the operand. The MSB sets the carry and 
extend bits, the LSB is set to zero. 


X/C 


1 — • — k =° 


LET ea=ea * 2 
LET Oy-Oy * (2aDx) 
LET Dy-Dy * (2a5) 


LSL ea (shi ft 1 ) 

LSL Dx,Dy (reg modulo 64) 
LSL #5. Dy (shift 1 to 8) 


LSR: Logically Shift Right the bits of the operand. 

The MSB is set to zero and the LSB sets the carry and extend bits. 



LET ea= I NT (ea/2 ) 

LET Dy=INT(Dy/(2ADx) 
LET Dy-INT(Dy/(2A5) 


LSR ea (shift 1) 

LSR Dx.Dy (reg modulo 64) 
LSR #5 . Dy (shift 1 to 8) 


MOVE: Move the byte, word or longword contents of the source effective address 
to the destination effective address. 


LET D1 =D0 

LET SP=SP-4: POKE(SP) , D7 
POKE(SP) .07 : LET SP=SP+4 


MOVE ea.ea 
MOVE 00,01 
MOVE 07, - (SP) 
MOVE (SP)+ . D7 


Use MOVEA where the destination is an address register. 





Instruction summary - continued 


MOVE from SR: Save the word contents of the status register in the effective 
address register or memory Location. 

Be careful as this instruction is privileged in the MC68010 and MC68020 instruction 
sets, programmers should try not to use it in user state. 

HOVE SfUa 

LET DO=PEEK_W(SR) HOVE.W SR, DO 


MOVE to CCR; Move the contents of the source operand WORD into the 
condition code register. 

Only the low -order byte is used; the upper byte is ignored. 

MOVE ea.CCR 

POKE_W(CCRM M0V£ 

Set the Zero flag and clear all others. 


MOVE to SR: Move the contents of the source operand into the status register. 

This is a privileged instruction and attempted access while in user mode will cause a 
trap to the privilege violation exception vector. 

HOVE ea,SR 

PQKE_W(SR) ,1792 MOVE #1792 , SR 

Clear all flags, set user state, and set interrupt mask to level seven. 


MOVE USP: Move the contents of the user stack pointer to or from the specified 
address register. 

This is a privileged instruction and attempted access while in user mode will cause a 
trap to the privilege violation exception vector, 

LET A3=USP MOVE USP, A3 

LET USP-A3 MOVE A3, USP 


MOVEA; Move the contents of the source effective address to the destination 
address register. 

Byte-sized operations are not permitted. 


LET A3=PEEK_W( 1 92) 
LET AO * PE EK_L { 4 } 


MOVEA. W 192. A3 
MOVEA. L 4, AO 
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Instruction summary - continued 

MOVEM: Move multiple registers to or from memory which permits the transfer of 
a block of specified registers to and from memory in a predetermined sequence bv 
one instruction. 

LET A7-A7-4 : P0KE_L{A7) ,DG MOVEM. L #57344 ,-{A7) 

LET A7=A7-4:P0KEJ.{A7),D1 
LET A7=A7-4: P0KE_L(A7) ,02 

HOVEH.L (A7) + ,#1 860 

Saves registers DO, D1 and D2 in order on the stack and then recovers them in the 
reverse order. 

These instructions save registers DO, D1 and D2 

(MOVEM T # 7 , 24 (A7) 

(MOVEM . L #57344, -(A7) * 

These two instructions recover registers DO, D 1 and D2 

(MOVEM. L 24 (A7) r #7 
(MOVEM. L (A7) + .#7 

* The predecrement mode of addressing values the registers in reverse order for the 
register list mask, permitting push-on, pull-off on a last in- first out basis. 


MOVEP: Move data to or from a data register and alternate bytes in memory. 
Enables the MC68000 to interface with 8-bit peripheral devices. The data is 
transferred on either the high half of the data bus D8-D15, even addresses, or the 
low half D0-D7, odd addresses, to memory occupying alternate bytes in the 
processor’s memory map. The data is transferred in high -low order. 

P0KE_W(7 + 65536) , Dn MOVEP Dn t d(Ay) 

LET Dn-PEEK_W{7+65536) MOVEP 7(Ay),Dn 

This is the only instruction that provides word and longword access at odd 
addresses. 


MOVEQ: Move sign -extended 32-bit immediate data in the range of + 127 to -128 
to a data register. 

A fast means of loading small positive and negative integers into a data register. 


LET DO-0 


MOVEQ #0,00 


Instruction summary - continued 


MULS: Multiply two signed 16-bit operands. 

Only the low -order 16-bits are used from both operands for the multiplication* the 
result being the 32-bit product in the destination data register. 

MULS ea r Dn 

ASL ea is a fast signed multiply by two. 


MULU: Multiply two unsigned 16-bit operands. 

Only the low -order 16-bits are used from both operands for the multiplication, the 
result being the 32-bic product in the destination data register. 

MULU ea, Dn 


NBCD: Negate Decimal with Extend. 

Subtracts the destination byte-sized operand and the extend bit from zero using 
decimal arithmetic. 

NBCD ea 

Extend bit dear, the ten’s complement is produced. 

Extend bit set, the one’s complement is produced. 


NEG: Negate subtracts the destination operand from zero, producing the two’s 
complement of a byte, word or long word operand. 


MEG ea 


NEGX: Negate with extend subtracts the destination operand and the extend bit 
from zero, producing the two’s complement of a byte, word or long word operand. 

NEGX ea 


NOP: No OPeration . 

Has no effect other than to increment the program counter by 2. Its use is generally 
either for creating a space in code which may be used Later on for adding a 
subroutine call, for writing text etc. or for deleting parts of code, especially test 
routines, without the need for recompiling. 
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Instruction summary - continued 


NOT: Logically complement. 

Produces the one’s complement of the operand. 

NOT ea 


OR: Or the source to the contents of the destination data register. 

The source OR data is normally used to set specific bits of an operand. 

LET Dn=src p | Dn OR ea h Dn 

If sre — 3, then OR sre sets bits 0 and 1 in Dn; the other bits are left unchanged. 

Use OR ea,Dn where the destination is a data register. 

Use ORI where the source is immediate data. 

ORI: ORI the immediate data to the destination effective address. 

ORI .W #51 2 , DO 

LET ea-data || ea Set bit 9 of word, others unchanged 

ORI to COR: ORI the data to the condition code register. 

LET CCR=6 | | CCR qrj 

ORI is used to set bit positions: Zero and Carry (bits 0 and 2 in the CCR) are set. the 
others are unchanged. 


r> 


ORI to SR: ORI the data to the status register 

LET SR-1792 OR SR 


ORI #1 792 , SR 


J 


Set the status register interrupt mask to level seven, all other conditions unchanged. 
This is a privileged instruction and attempted access from user mode will cause a 
trap to the privilege violation exception process routine. 


3 

1 
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instruction summary - continued 

PEA: Push effective address. 

Pushes a long word -computed address onto the current stack. It is useful for passing 
parameters to a subroutine which are accessed via an address register indirect with 
displacement instruction and removed from the stack prior to return if necessary. 

PEA param 
JSR sprog 

Access parameter sprog MOVE A, L 4($P),A0 

Tidy stack MOVE . L (SP) + .(SP) 


RTS 


RESET: Reset external devices by asserting the reset line. 

There is no affect on the processor other than an increase of two in the value of the 
program counter* This is a privileged instruction and attempted access while in user 
mode will cause a trap to the privilege violation exception vector. 

RESET 


ROL: ROtate without extend Left* 

The MSB is rotated to the LSB and the carry; the other bits are shifted up one* 



ROL ea (shift 1} 

ROL E)x r Dy (Reg modulo 64) 
ROL #5, Dy (shift 1 to 8) 


ROR; ROtate without extend Right* 

The LSB is rotated to the MSB and the carry; the other bits are shifted down one* 



ROR ea (shift 1) 

ROR Dx.Dy (reg modulo 64) 
ROR #5 . Dy (shift 1 to 8) 
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instruction summary - continued 


RGXL: ROtate with eXtend Left* 

The MSB is rotated to the extend bit and the carry, the extend bit is rotated to the 
LSB and the other bits are shifted up one. 












ROXL ea (shift 1) 

ROXL Ox . Dy (reg modulo 64) 
ROXL #5,Dy (shift 1 to 8) 


ROXR: ROtate with eXtend Right, 

The LSB is rotated to the extend bit and the carry, the extend bit is rotated to the 
MSB and the other bits are shifted down one. 


X/C 


ROXR ea (shift 1) 

ROXR Ds.Dy (reg modulo 64) 
ROXR #5,Dy (shift 1 to 8) 


RTE: Return from Exception. 

The status register and the program counter are pulled from the current (supervisor) 
stack. This instruction is privileged and attempted access while in user mode will 
cause a trap to the privilege violation exception vector* 


(SPJ+.SR RTE 
(SP)t.PC 


RTR: Return and Restore* 

The condition code and then the program counter are pulled from the current stack. 


(SPJ+.CCR RTR 
(SP) + , PC 


RTS: Return from Subroutine* The program counter is pulled from the current 
stack. 


(SP)+,PC RTS 
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Instruction summary - continued 

SBCD: Subtract Decimal with Extend. 

Subtract a byte-sized binary coded decimal number and the extend bit from the 
destination operand byte using decimal arithmetic and store the result in the 
destination location. 


SBCD $7 SBCD $27 

$6 516 

$1 $11 


MOVE #4 , CCR 
SBCD D0.D1 


Note that the z-flag is cleared if the result is non-zero, otherwise it is unchanged. 
For memory additions the data must be stored with the most significant digit lower 
in memory and the address register pointers initially set to the byte above the low- 
order BCD digit. The only memory addressing mode is predecrement. 


See: Set according to condition. 

The specified condition is tested and the byte specified set to all ones if true or all 
zeros if false. The condition may be: 



2’s complement 
arithmetic 

EQ Equal To 
NE Not Equal 
MI Minus 
PL Plus 
HI Higher than 
LS Lower than or same 

CS Carry Set 
CC Carry Clear 
VS Overflow 
VC No Overflow 
T True 
F False 

GT Greater than 
LT Less than 
GE Greater than 

or Equal to 
LE Less than or 

Equal to 


See ea 


STOP: Load the status register and Stop. 

The immediate operand is put into the status register and the program counter 
advanced to the next instruction and then stopped. Execution only resumes when a 
trace* interrupt or reset exception occurs. 

STOP #7 


SUB: Subtract the source from the destination. 

One of the integers must be the contents of a data register. 


LET Dn=Dn - ea 
LET ea=ea - Dn 


SUB ea .Dn 
SUB Dn , ea 


Use SUB ea 3 Dn where the destination is a data register. 
Use SUBA where the destination is an address register. 
Use SUBI or SUBQ where the source is immediate data. 
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Instruction summary — continued 

SUBA: Subtract the contents of the effective address from the contents of the 
destination address register. 

LET An -An - ea SUBA ea.An 


SUBI: Subtract a constant value from the contents of the destination effective 
address. 

Use SUBQ for speed and small integers. 

LET ee=ea - 999 SUBI #999, ea 


SUBQ: Subtract a constant of from 1 to S from the contents of the effective address. 
Faster subtraction than SUBI. 

LET ea-ea - 8 SUBQ #8.ea 


SUBX: Subtract either register to registers or predecremented memory from 
memory s with extend. 

The extend bit enables multiprecision arithmetic to be performed, acting as a 
borrow between successive operations. 

Data register subtractions 
Subtract two 64 bit integers 
D0_D1 and D2_D3 Lo-Hi resply 
SUB . L 00 , D 2 Low bits 
SUBX LD1.D3 High bits 

Memory addition 
MOVE #4, CCR 
SUBX. L -(AO), -(At) 

SUBX. L -(AO).-(AI) 

Note that the z-flag is cleared if the result is non-zero, otherwise it is unchanged. 
For memory additions first clear the Extend bit and set the Zero flag. The data must 
be stored with the most significant digit lower in memory and the address pointers 
initially set the operand size above the low order digit. Predecrement is the only 
memory addressing mode. 


Memory subtractions 
SUBX -(Ay), -(Ax) 

Where X infers the Extend bit 

LET Ay=Ay-4 
LET Ax c Ax-4 


POKE (Ax) , PEEK ( Ax ) - PEEK(Ay) -X 


SWAP: Swap register halves exchanges the high-order word of a data register with 
the low-order word. 

This instruction provides access to the low-order byte of the high word. 


Dn 0--15 < - - > Dn 16-31 
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Instruction summary - continued 


TAS: Test and set an operand, compares the operand byte with zero and sets the 
condition codes accordingly. 

If the byte is zero, the Z_flag is set; if the MSB is non- zero, then the N_flag is set. 
The MSB of the operand is then set. 


TAS ea 


TRAP: Trap. The processor commences execution at the relevant trap exception 
vector address. 


TRAP #n 


TRAPV: Trap on Overflow. 

The processor commences execution at the trap on overflow exception vector 
address. 


TRAPV 


TST: Test an operand. 

The operand is compared with zero and the condition codes set accordingly. 


TST ea 


Use in preference to CMP! #0 3 ea 


UNLK: Unlink. 

The stack pointer is loaded from the specified address register; the address register 
is then loaded with the longword pulled from the top of the stack and the linked 
space deallocated. 


UNLK An 



Appendix H - MC68000 
Instruction Codes 



H-2 


The Motorola MC68000 series of microprocessors rationalize mstruction 
allocation by segmenting the 16-bit Operation Word into five smaller blocks, each ot 
which has a fairly consistent meaning. Operation word instruction 


5 14 13 12 

11 10 9 

8 7 6 

5 4 3 2 

1 0 

| Type 

\ dreg 

! dmod | 

| smod ! 

sreg ; 


Instruction Word Parsing Analysis 


Type 


|l5 

14 | 

E 

CO 


The types 0 to 15 instruction codes (16 classes) are allocated as follows. 


Type Instructions Range 

0 Bit manipulation, Move Peripheral and Immediate instructions 

1 Move byte Instructions 

2 Move longword instructions 

3 Move word instructions 

4 Miscellaneous instructions 

5 Add Quick, Subtract Quick, Set conditionally and Decrement 
instructions 

6 Branch conditionally instructions 

7 Move Quick instructions 

8 Or, Divide and Subtract decimal instrs. 

9 Subtract, Subtract extended instrs. 

10 Unassigned 

1 1 Compare, Exclusive Or instructions 

12 And, Multiply, Add decimal and Exchange instructions 

1 3 Add, Add extended instructions 

14 Shift and Rotate instructions 

1 5 Unassigned 


H - 3 



Dreg 


11 10 9 


Dreg has three main uses, normally holding the destination address in the general 
move instruction, one of the two register numbers for use in the specified instruction 
or embedded data for use in the add and subtract quick instructions. 

Dreg only refers to a register in those instances where the instruction has two register 
operands. 

Dmod 

EEEL 

Dmod has two main uses, specifying the effective address mode of the destination 
operand in the general move instruction or, in most other cases it defines the size of 
the operation to be performed. 

Smod 


St 

E! 

E 

E 

'e 

£ 


■ : 

! 

k 


5 I 4 


n 


Smod usually defines the effective address mode of the instruction, the source 
operand for the move instruction, 

Sreg 


2 10 


Sreg defines the effective address register, usually the source. 
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Instruction codes 


BIT MANIPULATION, MOVE PERIPHERAL 
AND IMMEDIATE INSTRUCTIONS 


Type 1 (Bits 15-12) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Cond Codes 

syntax 

11-9 

8-6 

5-3 2-0 

Mode 

X N VC 

BCHG Dn , ea 

Dn 


5 


- ea- 

dataltadd 

--A-- 

BCHG data.ea 

4 


1 


- ea- 

dataltadd 

--A-- 

BCLR Dn , ea 

Dn 


6 


- ea— 

da ta had d 

--A-- 

BCLR data.ea 

4 


2 


- ea- 

dataltadd 

--A-- 

BSET Dn . ea 

Dn 


7 


- ea- 

dataltadd 

- - A - - 

BSET data . ea 

4 


3 


- ea- 

dataltadd 

- - A - - 

BIST Dn , ea 

Dn 


4 


- ea- 

dataddmd2 

- - A - - 

BIST data.ea 

4 


0 


-ea- 

dataddmd2 

- * A - - 

MOVEP Dx,d(Ay) 

Dx 

1 

1 

X 

1 Ay 

* 


MOVEP d (Ay) ,0x 

Dx 

1 

0 

X 

i Ay 

- 


OR T data.ea 

Q 

0 

s 

s 

-ea- 

dataltadd 

- A A 0 0 

OR I data r CCR 

0 


0 


7 4 

- 

A A A A A 

OR I data.SR 

0 


1 


7 4 

- 

A A A A A 

AND! data.ea 

L 

0 

s 

s 

-ea- 

dataltadd 

- A A 0 0 

ANDI data , CCR 

1 


0 


7 4 

- 

A A A A A 

ANOI data, SR 

l 


1 


7 4 

- 

A A A A A 

SUB T data,ea 

2 

0 

s 

s 

-ea- 

dataltadd 

A A A A A 

ADDI data.ea 

3 

0 

s 

s 


dataltadd 

A A A A A 

EGRI data, ea 

5 

0 

s 

s 

- ea- 

dataltadd 

- A A 0 0 

EORl data, CCR 

5 


0 


7 4 

- 

A A A A A 

EORI data, SR 

5 


1 


7 4 

- 

A A A A A 

CMPI data . ea 

6 

0 

s 

s 

- ea- 

dataltadd 

- A A A A 
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a 

a 

-a 

a 

i 

a 

a 

•a 

a 

a 

a 

a 
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MOVE BYTE INSTRUCTION 


Type 1 (Bits 15-12) 


Instruction 

syntax 

Dreg Dmod Smod Sreg 
11-9 8-6 5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

MOVE . B ea, ea 

source 

destination 

— ea- 

- ea- 

ALL* 

dataltadd 

- A A 0 0 

* Address register direct mode is not permitted 



MOVE LONGWORD INSTRUCTION 

Type 2 (Bits 15-12) 



Instruction 

syntax 

Dreg Dmod Smod Sreg 
11-9 8-6 5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

MOVE. L ea , ea 

source 

destination 

-ea- 

- ea- 

ALL 

dataltadd 

- A A 0 0 


MOVE WORD INSTRUCTION 


Type 3 (Bits 15-12) 



Instruction 

syntax 

Dreg Dmod Smod Sreg 
11-9 8-6 5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

MOVE W ea , ea 
source 

-ea- 

ALL 

- A A 0 0 


destination - ea - ataltadd 
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MISCELLANEOUS INSTRUCTIONS 


Type 4 (Bits 15-12) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Cond Codes 

syntax 

11-9 

8-6 

5-3 2-0 

Mode 

X N VC 

NEGX ea 

0 

0 s s 

-ea - 

dataltadd 

A A A A A 

CLR ea 

1 

0 s s 

-ea- 

dataltadd 

-0100 

NEG ea 

2 

0 s % 

-ea - 

dataltadd 

A A A A A 

NOT ea 

3 

0 s s 

- ea- 

dataltadd 

- A A 0 0 

MOVE SR . ea 

0 

3 

- ea- 

dataltadd 


MOVE ea, CCR 

2 

3 

- ea - 

dataddmdl 

A A A A A 

MOVE ea , SR 

3 

3 

- ea- 

dataddmdl 

A A A A A 

SWAP On 

4 

1 

0 Dn 

— 

- A A 0 0 

EXT.WDn 

4 

2 

0 Dn 

— 

- A A 0 0 

EXTADn 

4 

3 

0 Dn 

— 

- A A 0 0 

NBCD . G ea 

4 

0 

“ ea- 

dataltadd 

A u A u A 

PEA ea 

4 

1 

- ea- 

conaddmdl 


MOVEM 1 ist t ea 

4 

0 1 x 

- ea- 

conaltadd 


MOVEM ea .list 

6 

0 1 x 

- ea - 

conaddmd2 


TST ea 

5 

0 s s 

-ea - 

dataltadd 

- A A 0 0 

TAS ea 

5 

3 

- ea- 

dataltadd 

- A A 0 0 

ILLEGAL 

5 

3 

7 4 

— 


TRAP data 

7 

1 

0 0 v v v v — 



LINK An . data 7 1 

UNLKAn 7 1 

MOVE An f US P 7 1 

MOVE USP , An 7 1 


RESET 7 16 0 

m? 7i6i 

STOP data 7 16 2 

RTE 7 16 3 

RTS 7 16 5 

TRAPV 7 16 6 

RTR 7 167 


A A A A A 
A A A A A 


2 An 

3 An 

4 An 

5 An 


A A A A A 
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Type 4 (Bits 15-12) 


Instruction Dreg Dmod Smod Sr eg Address Cond Codes 

syntax 1 /— 9 8—6 5—3 2—0 A lode X N VC 


use on on H5 & H7 


Size 


s s Size 


Condition codes 


0 - Word 0 0= Byte 

1 = Longword 0 1— Word 

1 0= Longword 
ea = Effective address 
CCR = Condition code register 
SR - Status register 


u = Undefined 
A = Affected 
- = Unaffected 

0 = Cleared 

1 = Set 


ADD AND SUBTRACT QUICK, 
SET CONDITIONALLY and 
DECREMENT INSTRUCTIONS 

TypeS (Bits 15-12) 


E: = 3 
f, g 3 
I g 3 

•» — g' 

■ 

■ 

* ; = 3 

I 

Sj — 1 
= = i 


Instruction 

syntax 

Dreg Dmod 
11-9 8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

AddQ data .ea 
SUBQ data.ea 

data 0 s s 

data 1 s s 

- ea- 

- ea- 

altaddmod 

altaddmod 

A A A A A 
A A A A A 

See ea 

c c c c 1 1 

- ea- 

dataltadd 


DBcc Dn.data 

ccccl 1 

1 Dn 

— 


x Size 

s s Size 

Condition codes 


0 = Word 

1 = Longword 

0 0= Byte 
0 1— Word 

u 

A 

- Undefined 
= Affected 



1 0^ Longword 
ea = Effective address 
CCR = Condition code register 
SR — Status register 
c c c c = 4-bit Condition code 

v v v v = 4— bit Vector address 


- = Unaffected 

0 = Cleared 

1 = Set 
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BRANCH CONDITIONALLY INSTRUCTION 


Type 6 (Bits 15-12) 


Instruction 

Dreg 

Dmod Sniod Sr eg 

Address 

Cond Codes 

syntax 

11-9 

8-6 5-3 2-0 

Mode 

X N VC 

Bcc data 

c c c c displacement 

— 


BSR data 

0 

1 displacement 

— 


BRA data 

0 

0 displacement 

— _ 


x Size 

s s Size 

Condition codes 



0 = Word 0 0= Byte 

1 = Long word 0 1= Word 

1 0= Longword 
ea = Effective address 
OCR = Condition code register 
SR = Status register 


u = Undefined 
A — Affected 
- = Unaffected 

0 = Cleared 

1 - Set 


CONDITIONAL TESTS 


cc 

Mnemonic Condition 

0 

T 

TRUE 

1 

F 

FALSE 

2 

HI 

HIGH 

3 

LS 

LOW or SAME 

4 

CC 

CARRY CLEAR 

5 

CS 

CARRY SET 

6 

NE 

NOT EQUAL 

7 

EQ 

EQUAL 

8 

VC 

OVERFLOW CLEAR 

9 

VS 

OVERFLOW SET 

10 

PL 

PLUS 

11 

MI 

MINUS 

12 

GE 

GREATER or EQUAL 

13 

LT 

LESS THAN 

14 

GT 

GREATER THAN 

15 

LE 

LESS or EQUAL 


There is no Branch TRUE BT or Branch FALSE BF, the codes are used by the 
BSR and BRA instructions 
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MOVE QUICK INSTRUCTIONS 


Type 7 (Bits 15-12) 


Instruction 

syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sr eg 
5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

MOVED data, On 

Dn 

0 

data — 

- 

A A 0 0 


2’s complement data value 


OR, DIVIDE AND SUBTRACT DECIMAL 
INSTRUCTIONS 

Type 8 (Bits 15-12) 


Instruction 

syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sr eg 
5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

OR ea r On 

Dn 

0 s s 

-ea- 

dataddmdl 

- A A 0 0 

OR Dn, ea 

Dn 

1 s s 

- ea- 

altmemadd 

- A A 0 0 

DIVU ea.Dn 

Dn 

3 

— ea — 

dataddmdl 

- A A A 0 

OJVS ea ,Dn 

Dn 

7 

- ea- 

dataddmd 1 

- A A A 0 

SBCD Oy, Dx 

Dx 

4 

0 Dy 


A u A u A 

S6C0 -(Ay), -(Ax) 

Ax 

4 

I Ay 

— 

A u A u A 

x Size 

s s Size 


Condition codes 


0 = Word 

0 0= Byte 

u 

= Undefined 


1 = Longword 

0 1= Word 

A 

= Affected 



1 0= Longword - 

= Unaffected 


ea = Effective address 


0 

— Cleared 


CCR = Condition code register 

1 

= Set 



SR = Status register 
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SUBTRACT AND SUBTRACT EXTENDED 
INSTRUCTIONS 


Type 9 (Bits 15-12) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Cond Codes 

syntax 

11-9 

8-6 

5-3 2-0 

Mode 

X N VC 

SUBA . W ea.An 

An 

3 

-ea - 

ALL 


SUBA.L ea.An 

An 

7 

- ea- 

ALL 


SUB ea . Do 

Dn 

0 s s 

-ea- 

ALL 

A A A A A 

SUB On, ea 

Dn 

1 s s 

-ea- 

altmemadd 

A A A A A 

SUBX Dy.Dx 

Dx 

1 s s 

0 Dy 

— 

A A A A A 

SUBX -(Ay) , -(Ax) 

Ax 

1 s s 

1 Ay 

— ■ 

A A A A A 


EMULATION INSTRUCTIONS - Type 10 (#$A) 


Normally available for the implementation of user— written routines and entered by 
ensuring four MSB of the op word or defined word constant are 1010 (10 dec), 
which will cause a trap to a user routine; other bits of op word may be used for 
parameter passing. The ST uses this instruction for initializing and operating the 
’A -line functions on which GEM VDI and subsequently GEM AES are based - so 
use with care. 

COMPARE AND EXCLUSIVE OR INSTRUCTIONS 


Type 11 (#$B) (Bits 15-12) 


Instruction 

syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

CMPA ea.An 

An 

x 1 1 

- ea- 

ALL 

- A A A A 

CMP ea , On 

Dn 

0 s s 

- ea - 

ALL 

- A A A A 

CMPM -(Ay), -(Ax) 

Ax 

1 s s 

1 Ay 

— 

- A A A A 

EOR Dn.ea 

Dn 

1 s s 

- ea- 

dataltadd 

- A A 0 0 


x Size 


s s Size 


Condition codes 


0 — Word 0 0= Byte 

1 - Long word 0 1— Word 

1 0= Longword 
ea = Effective address 
CCR = Condition code register 
SR — Status register 


u — Undefined 
A — Affected 
- = Unaffected 

0 = Cleared 

1 - Set 
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5 S' 3 
s I 3 

S I" 

■ | a 

* I S 

= ■ 3 
E| 3 

= j 3 

E; 3 

| 

E ™ 3 

“I 3 

Eg 3 

S 7 ^ 

| 

E " 3 

=i 3 

j 

: i 

■ i ' 

S = 1 


AND, MULTIPLY, ADD DECIMAL 
AND EXCHANGE INSTRUCTIONS 


Type 12 (#$C)(Bits 15-12) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Cond Codes 

syntax 

\'-9 

8-6 

5-3 

2-0 

Mode 

X N VC 

AND ea.Dn 

Dn 

0 s s 

-ea- 

dataddmdl 

- A A 0 0 

AND On . ea 

Dn 

1 s s 

-ea- 

altmemadd 

- A A 0 0 

MULU ea , Dn 

Dn 

3 

- ea- 

dataddmdl 

- A A 0 0 

MULS 63,01 

Dn 

7 

- ea- 

dataddmd 1 

- A A 0 0 

ABCD Dy.Dx 

Dx 

4 

0 

Dy 

— 

A u A u A 

ABCD -(Ay), -(Ax) 

Ax 

4 

1 

Ay 

— 

A u A u A 

EXGD Dx , Dy 

Dx 

5 

0 

Dy 

_ 


EXGAAx.Ay 

Ax 

5 

1 

Ay 

— 


EXGM Ox , Ay 

Dx 

6 

1 

Ay 

— 



ADD AND ADD EXTENDED INSTRUCTIONS 

Type 13 (#$D) (Bits 15-12) 


Instruction 

Dreg 

Dmod 

Smod Sreg 

Address 

Cond Codes 

syntax 

11-9 

8-6 

5-3 2-0 

Mode 

X N VC 

ADDA.W ea , An 

An 

3 

- ea - 

ALL 



ADDA. 1 ea.An 

An 

7 

-ea- 

ALL 



ADO ea.Dn 

Dn 

0 s s 

-ea- 

ALL 

A 

A A A A 

ADO On . ea 

Dn 

1 % s 

-ea- 

altmemadd 

A 

A A A A 

ADDX Dy f Dx 

Dx 

1 s s 

0 Dy 

— 

A 

A A A A 

ADDX -(Ay), -(Ax) 

Ax 

1 s s 

i Ay 

— 

A 

A A A A 

+ x- Size 

s s Size 


Condition codes 



0 = Word 

0 0= Byte 

u 

= Undefined 



1 = Longword 

0 1= Word 

A 

— Affected 




1 0= Longword - 

= Unaffected 



ea = Effective address 


0 

= Cleared 



CCR = Condition code register 

1 

= Set 




SR - Status register 
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SHIFT AND ROTATE INSTRUCTIONS 


Type 14 (#$E) (Bits 15-12) 


Instruction 

syntax 

Dreg 

11-9 

Dmod 

8-6 

Smod Sreg 
5-3 2-0 

Address 

Mode 

Cond Codes 
X N VC 

ASL Dx .Dy 

Dx 

1 s s 

4 Dy 

— 

A A A A A 

ASL data,Dy 

count 

1 s s 

0 Dy 

— 

A A A A A 

ASL ea 

0 

7 

- ea- 

altmemadd 

A A A A A 

ASR Dx r Dy 

Dx 

0 s s 

4 Dy 

— 

A A A A A 

ASH data , Dy 

count 

0 s s 

0 Dy 

— 

A A A A A 

ASR ea 

0 

3 

- ea- 

altmemadd 

A A A A A 

LSI Dx , Dy 

Dx 

1 s s 

5 Dy 

— 

A A A O A 

LSL data, Dy 

count 

1 s s 

I Dy 

— 

A A A 0 A 

LSI ea 

1 

7 

-ea* 

altmemadd 

A A A 0 A 

LSR Dx , Dy 

Dx 

0 s s 

5 Dy 

— . 

A A A Q A 

LSR data.Dy 

count 

0 s s 

1 Dy 

— 

A A A 0 A 

LSR ea 

1 

3 

-ea- 

altmemadd 

A A A 0 A 

ROL Dx , Dy 

Dx 

i s s 

7 Dy 

— 

- A A 0 A 

ROL data.Dy 

count 

1 s s 

3 Dy 

— 

- A A 0 A 

ROL ea 

3 

7 

- ea- 

altmemadd 

- A A 0 A 

RGR Dx , Dy 

Dx 

0 s s 

7 Dy 

— 

- A A 0 A 

ROR data , Dy 

count 

0 s s 

3 Dy 

— 

- A A 0 A 

ROR ea 

3 

3 

- ea- 

altmemadd 

- A A 0 A 

ROXL Dx , Dy 

Dx 

1 s s 

6 Dy 

— 

A A A 0 A 

ROXL data.Dy 

count 

1 s s 

2 Dy 

— 

A A A 0 A 

ROXLea 

2 

7 

-ea- 

altmemadd 

A A A 0 A 

ROXRDx.Dy 

Dx 

1 s s 

6 Dy 

— 

A A A 0 A 

ROXR data,Dy 

count 

1 s s 

2 Dy 

— 

A A A 0 A 

RGXR ea 

2 

3 

-ea - 

altmemadd 

A A A 0 A 

x Size 

s s Size 

Condition codes 


0 — Word 

0 0= Byte 

u 

= Undefined 


1 = Longword 0 1= 

1 0= 

ea — Effective address 

Word A 

Longword - 

0 

= Affected 
= Unaffected 
= Cleared 


CCR = Condition code register 
SR = Status register 

1 

= Set 
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EMULATION INSTRUCTION - Type IS (#$F) 

Normally available for the implementation of user-written rou tines , and entered by 
ensuring four MSB of the op word or defined word constant are 1111 (15 dec), 
directing the trap service to a user routine. Other bits of op word may be used for 
parameter passing. 

This service trap is used by the MC68020 processor for passing co-processor 
instructions. The ST uses it in processing the application environment services 
(AES), so be careful. 


6 

S 

S 

g 

e 

1 

E 

E 

E: 





E 



Appendix I - Error codes 


BIOS ERROR CODES 


Error 



code 

Function 

Comments 

0 

OK 

Successful operation 

-1 

Error 


“2 

Drive not ready 

Not ready, not attached or busy 

-3 

Unknown command 

Command not understood by device 

-4 

CRC error 

Soft error while reading sector 

-5 

Bad request 

Bad parameter, Cannot do request 

-6 

Seek error 

Drive could not seek 

-7 

Unknown media 

Foriegn media. Bad zero boot sect 

—8 

Sector not found 


-9 

No paper 


-10 

Write fault 


-11 

Read fault 


-12 

General error 

Reserved 

—13 

Write protect 

Read only or protected media 

—14 

Media change 

Media changed since last write or 
the rd/wr op not done (file error) 

-15 

Unknown device 

BIOS doesn’t recognize device 

—16 

Bad sectors 

Format yielded bad sectors 

-17 

Insert disk 

Disk not in drive (shell error) 
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BDOS ERROR CODES 


Error PC DOS Function 


code equiv Supported 

Not supported 

-32 1 Invalid function number 

-33 2 File not found 

-34 3 Path not found 

-35 4 No handles left 

(too many open files) 


-36 5 Access denied 

-37 6 

-38 7 

-39 8 Insufficient memory 

Invalid handle 

^0 9 

-41 10 ** Insufficient memory 

—42 11 ** Insufficient memory 

-43 12 

Invalid memory block address 

-44 13 

-45 14 

-46 15 Invalid drive specified 

-47 16 * * I n va 1 id operat i on 


—48 17 

-49 18 No more files 



* 

The list of PODOS equivalent error codes supported may be found by running the 
GEM demonstration program (Appendix L), 


MISCELLANEOUS ERROR CODES 


Error 

code Function 


^64 Range error 

-65 Internal error 

-66 Invalid program load format 

-67 Setblock failure due to growth restrictions 


I" 







Appendix J - BASIC GEM 


1-2 


fill 


ST BASIC provides the programmer with direct access to parts of the operating 
system AES and VDI interface. 

GEMSYS 

The AES control arrays are accessed through the AES parameter block (GB 
pointer), the block provides pointers to the other supplementary AES parameter 
blocks: 


Control table + 80 

Global array + 84 

Int_in table + 88 

Int_outtable + $C 

Addr_in table +810 

Addr_out tab 1 e +814 


Data input and output as specified in 
the AES traps and utility tables 
Chapter 3. 


in 

>ii 





The tables are used by the programmer to input data, call the appropriate GEM 
AES function, GEMSYS(n), and read any reply from the data placed in the output 
tables by the function. 

VDISYS 

The VDI parameter blocks are directly accessible from BASIC: 


contrl 

input 

ptsin 

input 

ptSGUt 

output 

intin 

input 

intout 

output 


tables 


The appropriate tables are loaded with data and the function called via VDISYS(l), 
the (1) being a dummy argument. Any reply is read from the output tables. 




GEMSYS 



VDISYS 

GB 

control 1 




global 


contrl 


i 

Indi rect 

ptsin 


i nt_out 

access 

ptsout 


addr_in 


intin 


addr.out i 


in tout 
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SYSTAB 

ST BASIC also provides access to a BASIC system table of the following read only 
pointers and parameters: 


Graphics resolution 

+ 80 

1 = 

high resolution 



2 = 

: medium resolution 



4 = 

: low resolution 

Editor ghost line style 

+ $2 

0 = thickened 

(Read/write) 


1 — intensity 



2 = skewed 



3 - underlined 



4 -outline 



5 = shadow 

Edit AES handle 

+ 84 

1 


List AES handle 

+ 86 

2 i 

default 

Output AES handle 

+ 88 

3 


Command AES handle 

+ 8A 

4 


Edit open flag 

+ 8C 



List open flag 

+ 8E 

0 — dosed 

Output open flag 

+ 810 

1 = open 

Command open flag 

+ 812 



Graphics buffer 

+ 814 

Longword 32K buffer pntr 

GEM flag 

+ 818 

0 = 

normal, 1 ^off 


The GEM flag is used to turn BASIC I/O off and increase the processing speed of 
GEM based operations. With BASIC partially off, the I/O functions involving the 
screen, mouse and keyboard are disabled, although disk I/O is still enabled. 

The BASIC functions can be re-enabled after the burst of speed for user input 

Not all GEM and VDI functions are available through BASIC, some of the BASIC 
housekeeping activities negate the effect of the functions. 

Cautionary notes: 

Ensure that evaluations of the graphic primitives take into account color. Many 
experiments may appear not to work simply because the writing color is the same as 
the screen backgound. 

Characters are written to the screen starting from the left-hand edge and will 
probably be obscured by the command screen border unless the programmer moves 
it out of the way. 

Use the mouse and the right button to draw a primitive, use the left button to change 
the primitive. Note the effect on a prim itive of crossing the left hand screen edge. 
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10 start: CLEAR: a#=gb: fntJftUt-PEEK(a#+12) 

20 FULLW 2 : CLEARW 2 

30 INPUT "GDP (1 to 9) \gdp 

40 IF gdp<1 or gdp>9 THEN GOTO start 

50 POKE systab+24,1 : REM BASIC I/O off 

60 POKE cont rl ,1 22: POKE contrl +2.0: POKE contrl+6,1 

70 GOSUB curson 

80 attribs: GEM$YS(79) 

90 x-PEEK(frtt_Out+:2) : REM x mouse 

100 y-PEEK(int„out + 4) : REM y mouse 

110 key-PEEK(gintout+6) : REM button state ni 1 Jeft_right 

120 ON key+1 GOSUB showcurs, done, drawpritn 

130 GOTO attribs 

140 done: POKE systab+24,O:G0T0 start: REM nasty return 
150 drawprim: REM 

160 COLOR 1 ,(RND*15)+1 .1 ,fiND*25.2 : REM random color 
170 IF mouse=Q THEN GOTO 210 
180 moose=0 

190 POKE contrl , 123: POKE contrl +2 , 0: POKE contrl+6,0 
200 VD I SYS ( 1 ) : REM hide cursor 

210 POKE contrl ,11 : in=Q : xop-x+50 : yop-y+50: rc=0 
220 pti n a 2 : I F gdp-4 THEN ptin=3:xop-0:yop=0:rc-50 
230 IF gdp=2 OR gdp=3 THEN ptin-4 : xop=0: yop-O: in=»2 
240 POKE contrl +2 ,ptin 

250 IF gdp e 6 OR gdp=7 THEN xop-50:yop-20: in=2 

260 IF gdp‘5 THEN xop=60:yop=40 

270 IF inoO THEN POKE contrl +6, in 

280 POKE contrl +10, gdp 

290 POKE ptsin.x 

300 POKE ptsin+2 ,y 

310 POKE ptsin + 4,xop 

320 POKE ptsi n+6 . yop 

330 REM IF ptin-2 THEN GOTO nxtin 

340 POKE ptsin+8,rc 

350 POKE ptsin+10,0 

360 REM IF pti n=3 THEN GOTO nxtin 

370 POKE ptsin+12,50 

380 POKE ptsi n+14 r 0 

390 REM nxtin: IF in=0 THEN GOTO draw 

400 POKE intin, (rnd*3600) 

410 POKE i ntin+2, (rnd*3600) 

420 draw: VDISYS(I) 

430 RETURN 

440 showcurs: IF mouse H THEN RETURN 

450 POKE contrl ,122: POKE contrl +2,0: POKE contrl+6,0 

460 curson: POKE intin ,0: VDISYS(I) 

470 mouse-1 : RETURN 

Look at the spelling of the variables, particularly contrl, if the program crashes. 
Although BASIC access to the processor is normally in user mode, PEEK and 
POKE instructions are performed in supervisor mode to provide access to ail parts 
of memory. 
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BASIC ASSEMBLER 

There are many ways of producing a combined BA SIC/ assembler program on the 
Atari ST computer, the following demonstrates one of them: 

First create the assembler subroutine of relocatable 68000 machine code that can be 
saved using a BASIC program similar to the following. 


10 

RESTORE 


20 

ZA$- M 1 2345678901 234567890'“: 

REM \Use either method to 

30 

2BS -STRINGS (100, ,,#M ) : 

REM /create space for code 

40 

y-VARPTRfZAS) : 

REM Somewhere to put code 

50 

DEF SEG=y : 

REM Set up loop offset 

60 

FOR a=0 TO n 


70 

READ x : POKE a,x; 

REM Put code into memory 

■80 

NEXT a 

30 

BSAVE "progl .asrn\y,n: 

REM Save code to disk 

100 

STOP 


200 DATA 

REM Byte sized data 


The machine code will probably be loaded into a space created within the main 
BASIC program by a dummy variable. Obviously, any number of different machine 
code utilities can be loaded into the same space dependant upon program state, or 
they may be stored in individual program spaces. 

Parameters are passed to the machine code routine on the user stack which contains 
an integer count of the number of parameters passed on top. The next item on the 
stack is a longword pointer to the 8-byte per parameter array. String variables use 
the array parameter as a pointer to the string. 

Output can be placed in predefined variables and if correctly formatted, read back 
by the BASIC program. 

10 ZB$=STRING$(100, 11 * 11 ) : 

20 2R$="1 2345678" : 

30 y a VARPTR(Z3S) : 

40 ans-VARPTR (ZRS) : 

50 BL0AD "progl .asm" r y: 


100 CALL progl (x ,y, ans) : 


REM Space to load code 
REM Space for reply 
REM Position for code 
REM Position of reply 
REM Load code front disk 


REM Call program code, 
passing parameters x 
and y, returning data 
in the variable ans 


An alternative might be to compile the code within the BASIC program proper if 
the machine code program length is quite short. 


HAND CODING 


Many programmers had their first contact with assembly language 
through hand coded 8-bit microprocessor routines embedded in short BAS - 
programs. MC68000 code is slightly more complicated to assemble than 8-bit co e, 
but is still perfectly manageable. 

Use tables of instruction types 0 to 1 5 (H5 to H 14), to generate the basic code i.e: 
4096 x type + 512 x dreg + 64 x dmod + 8 x smod + sreg 

and the address mode encoding table (H.15) to determine the effective address (-ea-) 
values if required. 

Example of a hand coded program 


Project; Monitor screen inversion Author: 
Version: 2 


Date: Dee /85 


Syntax 

Src 

Mnm 

Dest 

Mom 

type 

d 

dn 

reg 

10 d 
sn 

nod 


dec 

value 

Notes 

MOVE , W 

n 

-(SP) 

3 

7 

4 

7 

4 

16188 

Get old color 



-1 






-1 


M0VE.W 

n 

h;sp) 1 

3 

7 

4 

7 

4 

16188 




0 






0 


MOVE .W 

n 

^SP) 

3 

7 

4 

7 

4 

16188 




7 






7 


TRAP 

14 


4 

7 

1 


14 

20046 


ADDA.W 

n 

SP 

13 

7 

3 

7 

4 1 

57084 

Tidy stack 



6 






6 


EORI.W 

n 

DO 

0 

5 

1 

0 

0 

2624 

1 

Toggle col bit 0 

MQVE.W 

DO 

1 

-(SP) 

3 

7 

4 

0 

0 

16128 

Set new colour 

MOVE .W 

n 

-(SP) 

3 

7 

4 

7 

4 

16188 




0 






0 


MOVE M 

n 

-(SP) 

3 

7 

4 

7 

4 

16188 




7 






7 


TRAP 

14 


4 

7 

1 


14 

20046 


ADDA.W 

n 

SP 

13 

7 

3 

7 

4 

57084 

Tidy stack 



6 






6 


RTS 

,1 - 


4 

7 

1 

6 

5 

20085 

Return to basic 


labi 


00 

02 

04 

06 

08 

10 

12 

14 

16 

18 

20 

22 

24 

26 

28 

30 

32 

34 

36 

38 
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Use this type of program to load the code into a file on disk: 


10 

restore in=70 

20 

zbS = 

5tring$(1Q0/‘* M ) 

30 

y=va 

rptr(zbS) 

40 

def ; 

seg * V 

50 

for , 

3=0 to n step 2 

60 

read 

x:poke a. int (x/256) : poke a + 1,x mod 256 

70 

next 

a 

80 

bsave "b/w. asm" , y , n+2 

100 

stop 


210 

data 

16188,-1 ,16188,0,16188,7 

220 

data 

20046,57084,6,2624,1 

230 

data 

16128,16188.0,16188,7 

240 

data 

20046,57084.6 

250 

data 

20085 

3O0 

data 

0,0, 0,0. 0,0, 0,0, 0,0, 0,0.0 

310 

data 

0,0, 0,0. 0,0, 0,0, 0,0, 0,0,0 

320 

data 

0,0. 0,0, 0,0, 0,0, 0,0, 0,0,0 


and to toggle the screen or border color, run the following BASIC 
program which loads the file back from disk and executes it: 


10 zb&=stri ng$ (100. M# "} 
20 y e varptr(zb$) 

30 bload "xb/w. asm' 1 r y 

40 call y 

50 stop 


The following brief notes may be useful in compiling programs in the above 
manner: 

Entry to machine code level from BASIC is in supervisor mode. 

If you drop to user mode^ be careful where you place your stack. Perhaps you might 
like to use the following sequence of instructions that jump over your stack or data to 
the beginning of the executable code. DATA 17402,4,24576 + dis v .. 


Start 


LEA 4(PC) ,A1 
BRA dis 
Text or 
stack 
Program 
code 


Set A1 to start of text 

dis = 2 + text length (must be even) 


Start of program 


If in difficulties with a BRAnch or JuMP, surround with NOF’s to make the jump 
less sensitive to the count. 
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Project: 

Version: 


labi 


0 

2 

4 

6 

8 

0 

2 

4 

6 

8 

0 

2 

4 

6 

8 

0 

2 

4 

6 

8 

0 

2 

4 

6 

8 


Syntax 


Src 

Mnm 


Dest 

Mnm 


Author: 


type dmod sreg 

1 d r 8 l s ,T d 1 


Date: 


dec 

value 


Notes 



Appendix K - Program development 

tools 
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ATARI MC68000 ASSEMBLERS 

There are a number of assemblers available for the Atari ST programmer, they have 
small discrepancies in the assembly syntax used, no uniformity in the library and 
utility files supplied or of the method of creating an executable program. 

This makes it difficult for the inexperienced programmer to type as source a 
program listing created for another assembler, and to get it operational What I have 
tried to produce is an analysis of each assembler and a conversion chart that may 
help in isolating fairly straightforward problems. 

Where a published program uses a particular assembler specific facility (special 
macros etc,) then translation will not always be possible by simple substitution and 
there may be no easy solution. Hopefully the general assembler compatibility chart 
will indicate whether there is the likelyhood of a conversion. 

This guide is very much less than perfect, but it is an attempt at assisting 
inexperienced programmers in a very difficult field. 


The assemblers 

Very few of the assemblers provide programming details of the Motorola M68000 
processor instruction set, or teach the user basic assembler language programming. 
If the reader has not written assembly language programs before, the brief overview 
of the language in Appendix G and H should help. 


Seka 

The combined editor/assembler/monitor/debuggcr is held in a very compact 20K of 
code, this means that parts of the package are a bit weak. Although two editors are 
supplied, a line editor and a screen editor, neither performs block find and replace 
function. Use the Atari wordprocessor in non wp mode for major or block changes 
in large flies. What is likely to be more of a significant problem is the limitation to a 
leading letter for label and symbol names (the use of an underscore is very common 
in most libraries and the Atari system variables), A possible solution would be to 
substitute a little used letter for the leading underscore, say V. 

On the positive side, the Seka assembler generates absolute or relocatable executable 
code directly, has limited macro and conditional capability, and is a quick assembler 
for writing programs if you know what you are doing - some of the runtime error 
messages are incomprehensible with no guide in the manual as to what they arc 
trying to tell you. It is very convenient having all the fad! ties in one program, an 
assembly error leaves the editor at the erroneous Line for immediate correction and 
reassembly or the programmer may trace through the code with the 
monitor/ debugger. The editor also allows the programmer to type the source code in 
free format; the assembled output listing is automatically tabulated, but there is no 
way of simply listing the code to a primer in a tabulated form which makes the 
source difficult to read when trying to debug program logic errors. Source files 


K-3 


entered in a tabulated form are occasionally detabulated in parts of the assembly list 
file. The system for linking files i, a bit messy and very non-standard as are some of 
the assembler directives. The monitor/debugger allows the programmer to 
single/ multiple step through a program, examine registers, set breakpoints and 
provides all the necessary facilities to aid program debugging. It is important to 
ensure that program files are of even length; odd file lengths sometimes produce 
run-time errors not discovered by the debugger, which makes the fault extremely 
difficult to locate. The assembly syntax is pretty standard; labels must terminate in a 
colon, ‘movea* should be entered as ‘move’, the assembler correcting the syntax but 
strangely *adda 3 is acceptable. The 36 page manual limits the two examples to very 
simple TOS programs, one of which includes macros. The manual has a lot of 
ground to cover which it manages only at a fairly minimal level, i.e it does not 
provide enough information regarding the cause of errors - an error in a macro is 
flagged as an illegal operand in the calling code. The manual contains a very useful 
single page command summary. 

The package is very easy to use, although not as powerful as some of the other 
packages in this Appendix, As an assembler, it is complete with minimal libraries of 
DOS calls equates and GEM array generators. 

His oft 

A combined edi tor/as sembler with a seperate monitor/debugger. The Hisoft 
assembler employs include files to ease the access to the GEM and TOS functions 
and produces machine code directly. The include files require function parameters 
to be explicitly placed in the parameter arrays as per the assembler GEM example 
(Appendix L). The assembler package incorporates a selective GST compatible 
linker and docs not like labels followed only by comments on the same line. The 
editor is a full feature program with the minor omission of displaying and handling 
only one file at a time. 

The package contains include files of equates for BDOS, BIOS, extended BIOS 
calls, system variables and a GEM include file that provides program initialisation, 
VDI and AES constant equates and parameter array initialisation. The package does 
not provide details of the data (Chapter 3) to be placed in the arrays. 

The monitor/debugger besides supporting the usual step, set breakpoints, examine 
and modify registers and memory etc. enables the assembled program to be run and 
debugged using seperate screens for the graphics and the monitor output, a very 
useful feature. 

The documentation is well written and provides a good introduction for the 
beginner. 

A very friendly package that could benefit from the use of a RAM disk to hold all the 
files in memory at once. In a 512K machine, seperating the program into two 
components does not appear to provide the optimum "modus operandf. 
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GST 

The GST assembler package has a very good GEM based editor that enables up to 
four files to be worked on at the same time in multiple windows* copying blocks 
from one to another with ease. The only possible complaint regarding the editor 
could be the relatively slow loading of program and files and of cursor movement up 
and down within the file. 

The assembler can produce relocatable binary output suitable for the linker or 
executable code directly from position independant source. The executable code 
does not contain the standard Atari TOS file header preamble* which must be added 
by the programmer if the file is to act as a stand alone program. A very useful list of 
the instruction mnemonics is provided* as is information on the optimisation route 
taken in compiling code. The use of an underscore for the leading character of a 
label or symbol is not permitted, which entails a degree of non compatibilty with the 
standard Atari ST notation for some system variables and extended BIOS calls. 

The assembly of source is slow by virtue of the many disc accesses* but the use of 
RAM disc for compilation and the loading of all modules into memory together will 
obtain reasonable speed. There is no uninitialised data (BSS) d The GST linker is 
also supplied with the Metacomco macro assembler* it enables other high level 
language modules written in Pascal, Assembler and C to be linked together in a 
single program. 

The library supplied contains macro definitions of conditional structures. GEM and 
TOS libraries arc not supplied. 

The documentation consists of seperate (unindexed) assembler, editor and linker 
manuals, which are very well packaged in a ring binder, the manuals are very 
detailed, but may be difficult for the inexperienced assembly language programmer 
to read. 


1 1 



i i 



i! 


j» i 
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»4 
tm i 
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Metacomco 

The screen editor is good but does not follow the normal GEM style of access, 
although the user will very quickly adjust. The global ‘find and replace 3 is 
comparitively slow as the screen is re-written for each change. 

The assembler is slow in comparison with the smaller assemblers evaluated in this 
Appendix and would benefit greatly from the use of RAM disk. Symbols may be of 
up to thirty significant characters, but tabulated L dc > data values on one source line 
seperated by a comma and space are not permitted * the space may be used to 
introduce a comment. 

Metacomco supply the GST linker with their macro assembler which can produce 
either a binary file suitable for the GST linker or a CP/M 68K object file suitable for 
the DR link68 linker; which links to the complete DR set of GEM and TOS 
libraries, but is undocumented. 



■ U 
mm 
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The Metacomco assembler package is supplied with assembler source to the GEM 
libraries and a monitor program. The monitor provides breakpoints, a trace mode 
and register /memory change and examine facilities. 

The assembler suite of programs can be batched using the Menu 4- program 
provided. It enables the sequence of edit, assemble, link and run to be controlled by 
the menu file* which runs and loads each program producing the specified outputs as 
requested and entering the next stage automatically via a pause, wait or continue 
programmed instruction. 

The documentation is concise and very well laid out, but gives no additional 
explanation on assembly errors to that displayed on the screen during the assembly 
phase. 

Digital Research 

The Digital Research package can use any editor/word processor that is capable of 
producing an unformatted ASCII text file. 

The assembler, which is a reasonable implementation of the Motorola M680GQ 
assembly language, has no macro facilities but optimises instructions and branches 
to produce efficient code. 

The DR LINK68 linker provides access to the DR GEM and TOS libraries that 
consist of accessory and application header files* GEMDOS* BIOS, XBIOS* VDI, 
AES and floating point libraries. 

Although the assembler, linker and relocator programs can be installed as TTP 
(TOS Takes Parameters) files, the programs are much easier to run via the 
Activenture Corp. batch program. The additional use of a RAM disk to hold the 
files and programs produces a very reasonable response, eliminating much of the 
disc access. 


The development package was intended for software developers and not the general 
public, as such it is written with a high degree of technical jargon. Complete with no 
omissions, a veritable ‘War and Peace*. It provides information on all of the GEM 
VDI functions and makes no mention of those not implemented on the ST. 

DR C language modules may also be linked with the assembled source and DR 
libraries to produce executable programs. 

The package is supplied with the DR symbolic interactive debugger £ SID* enabling 
the program writer to test and debug M68000 executable code, either from TOS or 
GEM, read/ write/move blocks of memory* disassemble code or produce a hex 
dump, examine the CPU state, trace, run or step through the code. 


Compatibility table 

The analysis of each package necessarily concentrates on the flaws * looking for 
inconsistences and omissions. What may not be apparent is how good in absolute 
terms the packages are, any purchaser being able to justify the cost on technical 
excellence alone. 

It may be useful to give an indication as to the range of likely purchasers of each 
package: 

Kseka assembler 

Absolute beginner - competent programmer: very fast program development 

Hi soft devp ak 

Absolute beginner - competent programmer: fast program development, with 
GEM and TOS bindings. 

GST macro assembler 

Absolute beginner - expert: full feature assembler capable of linking with 
other high level language modules to form executable programs. 

Metacomco assembler 

Competent programmer - expert: full feature assembler with macros. DR*s 
linker may be used to provide access to the complete set of system libraries, 
and GST’s linker to link high level language modules into a combined 
language program. 

Digital Research assembler 

Software developer: not available to the general public. 
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GENERAL ASSEMBLER COMPATIBILITY 


Not exhaustive, merely a guide to what facilities are available. 


Function 

Hisoft macro 
assembler 

Digital 

Research 

GST macro 
assembler 

Metacomco 
macro assmble r 

Kseka 

assembler 

Editor 

GENST 

- 

Edit 

Ed 

All-in-one 






package 

multifile edit 

No 

Can use any 

Yes (4) 

No 

No 

scrcen/lme 

screen 

wordpro ccssor 

screen 

screen 

Line fir 






screen 

GEM 

Yes 

ASCII text. 

Yes 

No 

No 

Assembler^, /p) 

<*S) 

AS68(.S) 

(ASM) 

(.ASM) 

(■S) 

Output 

Executable 

Binary file 

Binary file or 

See linker 

Executable 

no link 

or binary 


executable 






(no file hdr) 



Optimizer 

Yes 

Yes 

Yes 

Yes 


Macros 

Yes 

No 

Yes 

Yes 

Yes 

conditional 

Yes 

Yes 

Yes 

Yes 

Yes 

Linker 

LINK ST 

LinkGS 

GST-LINK 

Can use either 

Relocatable 

Input 



Binary file 

GST-LINKor 

mode 

Submissions 


Batch file 

Control file 

DR’s LINK68 

only 

Output 



File-header 

and RELMOD 



GST 


reloc tab 

programs 

(odd 


compatible 


code 

(GST-LINK is 

format) 


linker 


data 

supplied) 





opt symb tabl 



Libs 






GEM 

Yes f limited J 

Yea (complete) 

No 

Yes (source) 

Yes (minimal) 

TOS 

Yes f limited/ 

Yes (complete) 

No 

No 

Yes ( minimal ) 

Maths 

No 

Yes 

No 

No 

No 

Monitor 

Yes 

— 

No 

Yes 

Yes 


(MONST) 



Supplied as 


Debugger 

Yes 

SID 

Not supplied 

a source 

Yes 



symbolic 

Linker can put 

example 




interactive 

debug symbols 

on disk. 




debugger 

in program 



Relocator prg 

No 

RELMOD 

No 

No 

No 

Symbols 

16 sig chars 


8 signi f char 

Upto 30 chars 


Label 1 col I 

Space 

Spc or colon 

Spc or colon 

Spc or colon 

Colon 

end J col n 

Space or t 

Colon 

Colon 

Colon 

Colon 

Directives 


Optional period 




Comment col 1 

* 

* 

* or; 

# or ; 

* or | 

col n 

space 

* 

; or space 

; or space 

> 

Case (Symbols) 

Selectable 

Significant 

Not signi fen t 

Selectable 

Not signifent 

Quotes 

Single/ double 

Single/double 

Single 

Single/double 

Single/ double 


GST assembler executable code must supply a TOS program header and be written 
in positition-independant code before it can be run. 


Default file extensions are given in brackets. 
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ASSEMBLER DIRECTIVES COMPATIBILITY 


Directive 

Explanation 

Hisoft 

Digital 

Research 

GST 

Meiacomco 

Kseki i 

Include (i/p) 

Text 

Data 

BSS 

even 

Insert external 
Tile 

Relocatable code 

Initialised data 
Uninitialised data 
Align to word 

Yes(.S) 

Ho 

No 

DSBSS= = 
Yes*** 

No Yes (.IN) 

(.MAC) 

Yes Section code 

Yes 

Yes No 

Yes *** 

Yes 

Yes (deD 

Yes 

Yes 

*** 

Abs. code 
via linker 
Code = = 

No 

Data - = 
Yes & odd 

ORG <addr> 

Absolute section 

Yes 

Yes 

Yes 

No 

Yes 

Common 

Common region 

No 

Yes 

Yes 

No 

No 

RORG 







<add> 

Adjust curr loen 

No 


Yes 

Yes 

No 

Offset 

Define table via 

No 

Yes 

Yes 

Yes 

No 


a DS directive 






OPT 

Select addr mode 

D iff meaning 

Ignored 

PC Or Abs 

No 

No 

Globl 

External label 

No 

Yes 

No 

No 

Yes 

Xref 

External name 

Yes 

Yes 

Yes 

Yes 

No 

Xdef 

Internal label 

Yes 

Yes 

Yes 

Yes 

No 


for external use 






Module 

Lnk mod name 

Yes 


Yes 



Comment 

Inc l comments 



Yes 




in linker listing 






Fqu 

Symbol 

Yes 

Yes 

Yes 

Yes 

Yes & = 

Equr 

Register 

Yes 



Yes 


Reg 

Register list 


Yes 

Yes 

Yes 


Set 

Temporary value 

Yes 

Uses Equ 


Yes 


DC 

Constant 

Yes 

Yes 

Yes 

Yes 

Yes 

DS 

Storage 

Yes 

Yes 

Yes 

Yes 


DCS 

Constant block 



Yes 

Yes 

Blk =* = 

RS 


Yes 




No 

Conditionals 


Yes 

Yes 

Yes 

Yes 

Yes 

IF eq,ne,gc 
ge,lt,1e 


Yes 

Yes 

No 

Yes 

If, Else 
IFB 

String c,nc 


Yes 

Yes 

Yes 

Yes 

No 

Symbol d^nd 


Yes 


Yes 

Yes 

No 

Library 







System 


GEM/TOS GEM/TOS/F 





P 

None 

None 

Minimal 

Macro 




If, Else, For 






While, Until 






Repeat, Case 



Sub nth arg 

\ n 

Not 

En] 

?n 

\n 


Sub unique #nnn 

\@ 

applicable 

[LI 

?o 

\@ 

Mask2 



Ignored 


Ignored 


IDNT 



Ignored 


Ignored 



*** DS and DC word and longwords automatically align to boundaries 
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fc = 3 


Ei 

SS = 3 

l i ** 

ffi - 3 

= S a 

" ■ 

5 = 3 
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ST. 5 3 

ten - 3 

e;3 

J_ ■ .* 
:: = 3 

;; 5 3 
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ASSEMBLER CONVERSIONS 

There are a number of assemblers available for the ST, each with different 
characteristics, this section is provided as an aid to translation of programs presented 
from alternative sources. 

One of the by-products of the compatibility information is that it provides the 
opportunity of generating a subset of directives and instructions that are of almost 
universal applicability, but compatibility does tend to look at the lowest common 
denominator. 

All of these programs have other attributes which provide a significant improvement 
in performance over the base standard, these improvements are not always apparent 
to the casual user but very handy to have if required. 

If you wish to write source for maximum compatibility with other assemblers, the 
following should minimise the problems: 

► Size all instructions (move, clr, lea etc. do not default) 

► Size branches (avoids masses of GST warning messages) 

► Avoid using reserved words for labels such as text, code etc. 

► Use a semicolon for all comments (except Hisoft and DR which should use a ***) 

► Do not tabulate DC data, added spaces do not travel well. 

► Limit label and symbol lengths to eight characters, 

► Use "EQU* directive, not * = \ 

► After text and data sections, it is wise to ensure that the PC is on a word 
boundary. Most programs use 'EVEN’, some assemblers use ‘DC and 4 DS’ with 
a.Wora X extension. 

Sizing instructions is perhaps the most difficult factor to come to terms with. I find 
it extremely difficult to ignore and not stop and read any warning messages, and 
become a little irritated to find that a branch "might be short* or that LEA has not 
got a .L extension. All warnings should be significant or else they will all be treated 
as superfluous information. 
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General conversion chart 


from l 

To 

Kseka 

To 

Hisoft 

To 

GST 

To 

Metacomco 

To 

DR 

Comments 

Macros 

MACRO 


MACRO A 

n.a. 

Program may use 


?L 

\1 

-[A] 

-+1 M 

Expand 

many labels that do 

Kseka 

>2 

\2 

-+ [B1 

-* \2 

code 

not appear to have 


?0 

-+ \@ 

-►[■LJ 

-» \@ 

in full 

any function. They 

comment 


— ► * 



— ► * 

will probably be 




Size 

Size 


breakpoints. 

Opcodes 



opcodes 
& branch 

opcodes 




blk 

ds 

— > ds 

-> ds 

-► ds 



Macros 

Hisoft 

comment 

Opcodes 


MACRO 


->?1 
-*■ ?2 
?o 


blk 


\1 

\2 

\@ 

* 


ds 


MACRO 

A 

-[A] 

-[B 

^[■L] 

Size 
opcodes 
& branch 


Si 2 e 

opcodes 


n,a. Places GEM data 
Expand directly into VDI 
code an d AE S ar rays . I f 

in full the source includes 
GEM calls, follow 
the examples in 
Appendix L 


Macros MACRO MACRO 


GST 

comment 

Opcodes 


► ?1 
► ?2 
► ?o 


► blk 


V 

\2 

\@ 

. * 


MACRO 

A 


[21 

[■L] 


ds 


MACRO n.a, Seems to like all 
\l Expand instructions sized 
\2 code or issues lots of 
-* \@ in full warning messages. 

Library of conditio- 
nal macros will 
cause problems. 
Code has to belong 
to a section. 


Macros 


MACRO 

A 

MACRO 

n.a. 

GEM lib supplied 



-[A] 

V 

Expand 

Implementation is 

Metacomco 

-► ?2 

[B] 

\2 

code 

standard but 

comment 

Opcodes 

-+ ?o 

-[■L] 

* 

Size 

branch 

\@ 

J 

in full 
in appx L' 

translation depends 
on the availability 
of the library used, 
(follow examples 

) 


blk 


ds 



-►code 

Section C 


-»data 

Section D 

Digital 

Research 

-►zlabel 

-►zlabel 

comment 

— ► i 

(add 

> 

Opcodes 

to all 
labels) 
blk 



TEXT 

BSS 

_label 


ds 


Delete any period 
directive prefix. 

No macro facilities 
but a full set of 
GEM libraries. Look 
at examples Appx L 
to see sheer power 
and how difficult 
translation will be 


Jf 


& = s 

I a 

i 

~ j 3 

m = s 

C! — J 

5 a 

W*M “ 


4 


K- 11 


The above table will help to eliminate some of the more straight-forward program 
conversion problems, those that remain are likely to be due to the use of assembler 
specific directives and or libraries (especially label errors). 

If a program is published, one assumes that any include file data will be generally 
available and can either be appended as an include file or the code integrated with 
the main program block of code. 

If your assembler does not have VDI and AES libraries, then to use GEM you will 
have to create the arrays and load the addresses as shown in the assembler GEM 
example in Appendix L. 

The chart is limited to simple conversions. Once include files and global label 
definitions are used, you will need to assemble the program, generate a list of the 
missing external labels and hopefully find them in the examples Appendix and/or 
the call listings Appendix E. 


Numbers 


E; = 3 

Binary 

ftxxxxxxxx 

x = 0 or 1 

= 1 ! 

Decimal 

nnnn 

n — 0 to 9 

5»lr S 3 

Hexadecimal 

Snnnn 

n— 0 to 9, atof 


J 


5=3 
r — 3 

; 

:: 
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BASIC CALLING PROCEDURES 

These are for simple source files assembled (and linked) without libraries* 

KSEKA 


SEKA>r 

FILENAMES lename 

$EKA>a 

0PTI0NS>v 


Instruction to read source file from disc 
File to read (default .S extension) 
Instruction to assemble source 
Option to view assembly on screen 


SEKA>wo Instruction to write output program 

FILENAMES i lename File to write (default . PRG extension) 


HISOFT 

Menu driven, place cursor over instruction and click 


Option --> Assemble 


Option dialog box 


Binary filename xxxxx.prg 

Listing option boxes (none/screen/printer/disc) 
Assemble/ cancel boxes 


GST 

Menu driven, place cursor over instruction and click, or double click the TTP 
program file and enter the filename as the parameter: 

ASM. PRG filename to produce a list file and filename, BIN from a default ASM extension 
file 

LINK. PRG filename to produce a MAP file and filename. PRG from a default BIN 
extension file 

METACOMCO 

The program files are installed as Tos Takes Parameters (TTP), double click and 
enter input file: 

ASS EM. PRG filename assembles filename.asm to produce a GST format output file 

LINK. PRG filename produces a MAP file and filename.PRG from a default .BIN 
extension file 

DIGITAL RESEARCH 

The program files are installed as Tos Takes Parameters and Research the file data 
entered into the parameter box. 

AS68.PRG filename. S Produce binary file 

LINK68 . PPG filename. 68K - filename. o Produce relocatable file 
RELM0D.PRG filename Produce absolute file 


Executable file sizes (bytes) 

Natural compilations with no optimisation extensions called 


Program 

Page# 

D.R 

Seka 

Hisoft 

GST 

Metacomco 

GEM error message 

L7 

111 

- 

- 

~ 

781 

Assembler GEM 

L8-L17 

1651 

1734 







3170 

3170 

3016 

3170 

TOS colour demo 

LI6 

145 

162 







246 

246 

235 

248 

TOS VT52 screen 

L18-19 

194 

202 

202 

192 

202 

TOS sound program 

L20-22 

324 

331 







591 

591 

586 

591 

A-line sprite prog 

L25-26 

296 

314 







394 

394 

374 

392 


The Metacomco file sizes are for files linked via the GST linker except for the 
‘GEM error message’ which used the DR linker. 

The Digital Research files are absolute files and therefore presumably nearer the 
minimum possible size. 


(a secondary figure is given which specifically sets all text and data sections 
initialised to provide standard file size compilation comparisons, not all of the test 
assemblers can handle an uninitialised section) 
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C COMPILERS 

Many C compilers have been developed for the ST range of computers, enabling the 
ST programmer to produce modular, well documented, easily maintained code that 
may be ported to other C systems with a minimum of effort. 

Although achieving the same end result, the C compilers differ considerably in the 
way that they attain that result. I give three examles of the compilation process: 

DIGITAL RESEARCH C 


Source text 


! 


Preprocessor 


Intermediate file 


I 


Parser 


Intermediate code file 


I 


Code generator 


Assembler text 


I 


Asembler 


Object file 


a Libraries 


Link68 


Executable program file 


Relocator 


Resolve define and include statements 


Produce an intermediate code file 


Generate assembly language source file 


Create an object file 


Link object file with run-time library and operat- 
ing system files 


Change the relocatable information to absolute 
data 


I i 
* m 


I I 




91 



Absolute program file 


GSTC COMPILER 


Source text 


C compiler 


Assembler text 


I 


Assembler 


Relocatable binary file 

Libraries 


i 


Link68 


Executable program file 


Resolve j define and include statements, produce 
assembly source file. 


Produce a relocatable binary file 


Link object file with run- tune library and operat- 
ing system files 


METACOMCO LATTICE C 


Source text 


I 


LC1 compiler 


intermediate quad file 


i 


LC2 compiler 


Binary file (GST or TOS format) 


Produce an intermediate file of logical records 


Produce either an object file (DR linker) or a 
relocatable binary file (GST linker ) 


Libraries 


Link68 


Executable program file 


Link object file with run-time library and operat- 
ing system files 


Those programmers who wish to program the Atari ST in C may find the following 
brief notes helpful. 

Unlike nearly all of the commercial assemblers, the C compilers supply a full set of 
GEM and system libraries. Commercial C compilers for the Atari ST will, in 
general, adhere to the GEM VDI and GEM AES function names used in this book, 
usually only the first 8 characters being significant. The compilers diverge 
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considerably in use of parameter names, the call and parameters are therefore not 
provided here to avoid confusion. The manual of the C compiler you are using will 
provide a definitive list of the library routines available, interfaces, and the required 
parameter size, sequence and annotation. 

Many compilers will have additional features to greatly simplify the task of writing 
GEM programs; but bear in mind that the use of these ‘super C’ GEM functions 
may put a restraint on program portability. A definite decision should be made as to 
whether the programmer is writing portable code or simply writing a program. 

On a more general note; it is very much easier to develop programs on a 1 Megabyte 
disk drive, which makes the larger drive well worth the small additional cost for 
chose machines without the built-in drive. 


Appendix L - Example assembler 
programs 


* 


f 


L “ 2 


The programs presented in this section illustrate some of the techniques involved in 
accessing parts of the Atari ST operating system and also present general purpose 
header/ include files. The programs are written as shells to which the programmer 
may add his/her own composition. 

It is not the intention to provide £ state of the art’ programs, merely demonstrate 
access to the various parts of the operating system. Any attempt at definitive 
programming would rapidly succumb to the passage of time and tend to produce a 
book of listings. The main place to find quality programs will be the computer 
magazines* where programs developed from this and other books will appear as 
programmers quickly find new* smarter routes to access and use the ROM routines. 

Desktop accessories should be compiled as applications for debugging purposes as it 
is not possible to execute an accessory. 

Program conversion key: 

n.a program not suitable for this assembler, 
xxx delete this line 

* use ; for Kseka, GST and Metacomco comments 
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GEM 


APPLICATION AND ACCESSORY HEADER FILE 

Digital Research (and Metacomco in CP/M 68K object mode) application and desk 
accessory files require a similar type of header source file construct to provide access 
to the GEM VDI and AES libraries* either as the first file in the DR link statement 
or as the beginning of a single block of assembler code. 

Part of this file determines the size of memory the application requires and returns 
the remainder to GEMDOS* Some Atari ST assemblers will provide similar code as 
a header/ initialisation file to permit the programmer to access the VDI and AES 
functions through their own integral libraries. 


* Digital Research 

# 

text 

* 

* Text segment 

* Hi so ft . 

* n.a . 

* 

GST Metacomco Seka 
n.a . n.a 

globl jn-ain 

* Make labels 

* 

. xdef , 

globl _crystal 

* accessible to 

# 

, xdef , 

globl _ctrLcnts 

* external files 


. xdef 


move. 1 a7,a5 * store stack (a5) * 

move.l #ustk f a7 * set local stack * 

* 

# Desk accessories do not require the following lines of code 

* which size memory and return the unused memory to GEMDOS 

» 

move,] 4 ( a 5 ) , a 5 # basepage address * 

move.l $c(a5),d0 # length of text * 

add.l $1 4 ( a5 ) . dO * length of data * 

add- 1 $lc(a5) .dO * length of BSS 

add.l #S100.d0 * basepage size * 

move.l dO,-(sp) * retained mem len 1 

move.l a5,-(sp) * memory to modify * 

move dO , - ( sp) * dummy word 1 

move #$4a,-(sp) # reallocate to GEM* 

trap #1 * function number * 

add.l #12,sp * tidy stack * 

* Main program call 

# 

jsr _main * main program code* 

move.l #0,-(a7) * return to GEMDOS * 

trap #1 * function call * 


L - 4 


IJ 


* Digital Research 

* GEMAES calls link through .crystal 


Hisoft GST Metacofflco Seka 


.crystal ; 
move .1 4(a7) , dl 
move.w #200 , dO 
trap #2 
rts 

# 

bss 

even 


address of AES pblk* 
GEMAES function # * 

function cal 1 
return # 

block storage seg * 
force even boundary* 


ustk : 


d$. 
ds . 


64 

1 


data 

even 

«• 

_ctrl_cnts 

* 

* Application manager 


dc.b 0,1,0 

* APPLINl 

.10 

# 

dc.b 2,1,1 

* APPLREAd 

.11 

« 

dc.b 2,1.1 

* APPI WR I te . , . . 

,12 

i 

dc.b 0,1,1 

* APPt FINd 

.13 

* 

dc.b 2,1,1 

* APPLTPLay. . , . 

.14 

ft 

dc.b 1,1,1 

1 APPLTREcord. . 

.15 

ft 

dc.b 0.0,0 

ft 


ft 

dc.b 0.0,0 

ft 


# 

dc.b 0,0,0 

» 


* 

dc.b 0,1,0 

* ARP LEX It 

.19 

# 

Event manager 



dc.b 0,1,0 

* EVNT.KEY 

.20 

* 

dc.b 3.5,0 

* EVNTJJUTton . . , 

.21 

* 

dc.b 5.5,0 

* EVNTJIOUse — 

.22 

ft 

dc.b 0,1,1 

* EVNTJIESsage. , 

.23 

ft 

dc.b 2,1,0 

* EVNT_TI Me 

.24 

ft 

dc.b 16,7,1 

* EVNTJIULti 

.25 

ft 

dc.b 2,1,0 

* EVNT.DCLick. . . 

.26 

* 

dc.b 0,0,0 

* 


* 

dc.b 0,0,0 

ft 


* 

dc.b 0,0,0 

ft 


* 


1! 

sr 

IT 

Itl 

nr 

t 

E 

E 

E 

E 

lilt 

$ 


m 


* Digital Research 


* Hisoft . GST Metacomo Seka 


* 


Menu 

manager 




dc . b 

1.U 

* MENU-BAR. . 

.30 


dc.b 

2,1,1 

* MENLLICHeck . . , 

.31 


dc . b 

2.1/1 

* MENlLIENable . . 

32 


dc.b 

2.1.1 

* MENLLTNOrmal . . 

.33 


dc.b 

1.1,2 

* MENlLTEXt 

.34 


dc.b 

1.1,1 

* MENOEGister . 

.35 


dc.b 

0.0,0 

* 



dc . b 

0.0,0 

* 



dc.b 

0,0,0 

* 



dc.b 

0.0,0 

* 



Object manager 



dc.b 

2,1.1 

* OBJC ADO 

.40 

• 

dc.b 

1,1,1 

* OBJC_DELete . . . 

.41 

ft 

dc.b 

6*1,1 

* 0BJC_DRAw 

.42 

ft 

dc.b 

4,1,1 

* 0BJC_FINd 

.43 

* 

dc.b 

1,3.1 

* 0BJC_0FFset, . 

.44 

* 

dc.b 

2,1,1 

* OBJC.ORDer. , . . 

.45 

f 

dc . b 

4,2,1 

* OBJC EDIt 

.46 

# 

dc.b 

8,1,1 

* OBJC_CHAnge. . . 

.47 

f 

dc.b 

0,0,0 

t 


* 

dc.b 

0.0,0 

ft 


ft 

Form 

manager 




dc.b 

1,1,1 

# FQRMDO 

.50 

ft 

dc . b 

9. LI 

* FORM_DIAlog, . , 

.51 

ft 

dc.b 

1.1,1 

* FORM_ALErt. . . . 

52 

# 

dc.b 

1.1,0 

* FORM ERRor. . . , 

.53 

ft 

dc.b 

0.5.1 

* FORILCENtre.. 

,54 

t 

dc.b 

0,0,0 

# 


t 

dc.b 

0,0,0 

* 


t 

dc.b 

0.0,0 

i 


# 

dc.b 

0,0,0 

i 


# 

dc.b 

0,0,0 

IF 


ft 


Digital Research 

Dialog manager 

dc.b 0,0,0 * 

dc.b 0,O r O # 

dc.b 0,0.0 # 

dc.b 0,0.0 # 

dc.b 0,0,0 tt 

dc.b 0,0,0 * 

dc.b 0,0,0 # 

dc.b 0,0,0 * 

dc.b 0,0,0 

dc.b 0.0,0 * 


Graphics manager 


dc.b 

4.3,0 

tt 

GRAF_RUBberbox 

.70 

dc.b 

8.3,0 


GRAF_DRAgbox . . 

.71 

dc.b 

6,1.0 

* 

GRAFJIOVebox . . 

.72 

dc.b 

8,1.0 

# 

GRAF_GROwbox . . 

.73 

dc.b 

8,1,0 

tt 

GRAF.SHRi nkbox 

,74 

dc.b 

4,1.1 

tt 

GRAF.WATchbox . 

.75 

dc.b 

3,1,1 

tt 

GRAFTS LI debox. 

.76 

dc.b 

0,5,0 

tt 

GRAF.HANdle 

.77 

dc.b 

1,1,1 

tt 

GRAF MOUse 

.78 

dc.b 

0,5,0 

tt 

GRAFJIKState . . 

.79 

Scrap manager 



dc.b 

0,1.1 

z 

SCRP_REAd 

,80 

dc.b 

0.1,1 

tt 

SCRP.WRIte 

81 

dc.b 

0.0,0 

tt 



dc.b 

0,0.0 

tt 



dc . b 

0,0.0 

# 



dc.b 

0,0.0 

tt 



dc.b 

0,0,0 

t 



dc.b 

0,0,0 

t 



dc.b 

0,0,0 

# 



dc.b 

0.0,0 

tt 




* Hisoft . GST Metacomco Seka 


# 

* 


* 


* 


# 

# 

* 

* 


# 

* 



Digital Research 
File selector manager 


* Hisoft . GST Metacomco Seka 


dc.b 

0,2,2 

4 FSELJNPut. . . 

..90 

* 

dc.b 

0,0,0 

* 



dc.b 

0,0,0 




dc.b 

0,0.0 



* 

dc.b 

0,0,0 

# 



dc.b 

0,0.0 

* 



dc.b 

0,0,0 

* 



dc.b 

0,0,0 

# 


* 

dc.b 

0,0,0 



#• 

dc.b 0,0,0 * 

Window manager 



dc.b 

5,1,0 

# WlND_CR£ate . . 

.100 

# 

dc.b 

5,1,0 

* WIND-OPEn. . . . 

,101 

# 

dc.b 

1,1,0 

1 WIND_CLOse. . . 

.102 

# 

dc.b 

1,1,0 

* WINOJJELete . . 

.103 

# 

dc.b 

2,5,0 

* WIND_GET. . . . . 

104 

t 

dc.b 

6,1,0 

* WIND.SET 

.105 

t 

dc.b 

2,1.0 

* WIND_FINd. . . . 

.106 

tt 

dc.b 

1,1,0 

* WINOPDate. . 

.107 

« 

dc.b 

6,5.0 

* WIND_CALc . . . . 

.108 


dc.b 0,0,0 # 

Resource manager 


* 

dc.b 

0.1,1 

* RSRC LOAd.... 

,110 

# 

dc.b 

0,1,0 

* RSRELFREe.... 

,111 

* 

dc . b 

2,1,0 

# RSRCLGADdress 

.112 


dc.b 

2,1,1 

* RSRC_SADdress 

.113 

* 

dc.b 

1.1,1 

* RSRC_OBFix. . . 

.114 

-» 

dc.b 

0,0,0 

# 



dc.b 

0.0,0 

* 


# 

dc.b 

0,0,0 

* 



dc.b 

0,0,0 

* 



dc.b 

Shel 

0,0,0 
1 manager 




dc.b 

0,1,2 

# SHELREAd 

120 

• 

dc . b 

3,1,2 

* SHELWRIte 

121 

* 

dc.b 

1.1,1 

t 


*■ 

dc.b 

1.1,1 

* 


tt 

dc.b 

0.1,1 

* SHELFINd 

124 

# 

dc.b 

0.1,2 

* SHELENVrn, . . . 

125 

* 


end 
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The object file is used as the first file in the link to produce an Atari ST program 
file, say myprog, that accesses the DR GEM libraries i.e: 

either DR 

asGS -} -u apstart. s 

or Metacomco 

assem.prg apstart .asm opt j 

followed by the linking of the main program file (see following example) to the 
header and the DR library files. 

1ink68 [u] myprog. 63=apstart myprog. o vdibind aesbind 

and finally relocated using: 
re 1 mod my prog 

Delete all temporary files, leaving either an application file myprog. prg (which may 
be run by double clicking the icon in the directory listing) or an accessory file which 
must be renamed myprog.acc. Reboot the system and run the file by clicking the 
icon in the list of ‘Desk 5 accessory files. 

Remember to initially compile and run accessories as applications to debug them. 


L - 9 


a 

3 

3 

a 

3 

3 

_3 

3 

3 

3 

3 

3 

3 

l 

1 

1 

H 


GEM DEMONSTRATION PROGRAM 

To use GEM directly, push the function parameters onto the stack in the order 
given by the GEM VDI and GEM AES tables, ensuring that the correct size of 
parameter is pushed. 

The following program, which may be written in either DR or Metacomco macro 
assembler but must use the DR link68 linker, lists in descending order the TOS 
error codes in dialog boxes, the user stepping from one code to the next via the 


mouse or the ‘return 5 key. 



# Digital Research 



* Hi soft 

GST Metacomco 

* 



* n d . 

n . , a . 

* Demo GEM program 

# 





g 1 obi _main 

* 


4 

. xdef . 

globl _form_err 

4 


4 

. xref . 

globl _appljni 

4 


« 

. xref . 

globl _app1_exi 

* 

4 


t 

, xref . 

text 



4 

. The 

* 



4 

Metacomco 

_main: 



4 

. external 

jsr _appl_ini 



4 

.symbol . 

t 



4 

. names . 

move.w #63.d4 

4 

Error start # 

4 

. are 

loop: move.w d4,temp 

4 

Save it 

4 

. 1 i mi ted . 

move.w d4 , - ( sp) 

4 

Stack it 

4 

. to 8 

jsr _foriLerr 

tt 

What is it 

4 

characters 

add.w #2 . sp 

t 

Tidy it 

* 

. i.e . 

move.w temp,d4 

t 

Recover it 

4 


dbra d4 f loop 

# 

and next 

4 

_form_er 

jsr _appl_exi 

4 

Controlled exit 

4 

_appl_in 

rts 

» 



4 

„appl_ex 

bss 

t 



4 

* 

temp: ds.w 1 



t 



end 
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The file may be assembled using: 
either DR 

as68 -1 -u -p my prog, s 

or Metacomco 

assem myprog - asm opt j 

Both programs are linked with the Digital Research link68 linker i.e 

1 ink68 [s t u] myprog, 68k=apstart< myprog .o, aesbi nd 

Finally relocate using: 
re 1 mod my prog 
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GEM DEMONSTRATION ASSEMBLY PROGRAM 

It is possible to write assembly language programs that do not use the DR GEM 
bindings but simply access the functions via the Extended BDOS TRAP #2 calls. 
The following example shell shows a technique that will enable the programmer to 
create a window, do some work in it, and then make a controlled exit. 

Note: Although the window is created with the sizing diamond and sliders, no code 
has been written to handle the screen managers requests for change ; if these 
functions are activated they are ignored. If the cursor is active (as in this program) 
and covers part of the foreground content of the screen when the program is loaded, 
it will leave a hole when moved. 


* Digital Research * Hi soft GST Metacomco Seka 

* 

* Assembler GEM program 


Size 

the job and free 

back to GEMDOS unused 

memory 

text 



* XXX 

section c 

move. 

1 37, a5 

* 

curr -> a5 * 


move. 

1 #ustk,a7 

* 

set local stk * 


move. 

1 4(a5},a5 

ft 

get base page * 


move . 

1 5c(a5).dO 

* 

text segment * 


add.l 

$14(a6},dO 

ft 

data segment * 


add . 1 

$1c(aS) ,d0 

ft 

uninitialized * 


add, 1 

#$100, dO 

ft 

basepage size * 


move . 

1 dO.-(sp) 

ft 



move . 

1 a6.-(sp) 

* 

# 


move 

dO.-(sp) 

# 

# 


move 

#$4a,-(sp) 

*free unused mem # 


trap 

#1 

# 

# 


add . 1 

#5c,sp 

* 

tidy stack * 


jsr 

Start 

# 



move . 

] #SQ.-(sp) 


ret to GEMDOS * 


trap 

#51 

* 

ft 



. code 


E 1 J 

s j 


# Technique for setting up VDI & AES arrays 

* 

* Initialize AES arrays 

# 

start: 



j sr ini_aes 


t 


i 

* 
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* Digital Research * Hisoft GST Metacomco Seka 

* Call APPLJNI (1st call) see section 3 

tt 

appl_ini : 

move .w #$a, control * 

move.w #$0 , control +2 * 

move .w #$i f control +4 

move.w #S0. control +6 * 

jsr aes * 

tst.w intjou * ■ 

bpl graf_han * 

rts * 

t 

* Call GRAF_HAN to get name of the currently opened window. 


graLhan : 


move.w 

#77 .control 

# 

move.w 

#$0.control + 2 

* 

move.w 

#$5, control+4 

* 

move.w 

#$0, control +6 

tt 

jsr 

aes 

* 

move . w 

int_ou, handle 

tt 

Initialize VDI arrays 


jsr 

inuvdi 


Open virtual workstation 


.opnvwk : 

move.w 

#1 00. contrl 

* 

move.w 

#0,contrl+2 


move .w 

#1 1 , contrl +6 

# 

move.w 

handle , contrl +1 2 


11 input parameters 


move , w 

#1 h intin *dri ve id 


move.w 

#1 k intin+2 Mine type 


move.w 

#1 p intin+4 Mine color 

* 

move . w 

#1 , intin+6 ‘marker type 

* 

move.w 

#1 , intin+8 ‘marker color 

# 

move . w 

#1 ( intin+10 ‘text face 


move.w 

#1 , intin+12 ‘text color 


move.w 

#1 , i ntin+1 4 Mnteri or fill 


move.w 

#1 , intin+16 ‘fill index 

« 

move.w 

#1 , intin+18 ‘fill color 

* 

move.w 

#2 , intin*2G *NDC/RC 

tt 

jsr 

vdi 

* 
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= 
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i 

i 

MS 
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.. 
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e - 3 

I 

E : - 3 

if I 

t | 3 

■r 

i 

|i , 

s : i 


i 


n: 


i 



* Digital Research * Hisoft GST Metacomo Seka 

* Save virtual screen workstation device handle 

move.w contrl+12. vhandl * 

tst.w contrl+12 * 

beq appl_exi # 

* Test here for screen resolution and number of colors available 

* (even in mono). Load appropriate resource file using the AES 

* R$RC_L0A call if necessary, 

* 

* Get max possible size of window 

* 

max_wind ; 

move.w vhandl . intjn * 

move.w #7,int_in+2 * sizes 1 

jsr wind_get *. 

tst.w int_ou * 

beq appl_exi * 

t 

* Calculate work area of window 

* 

move .w #0. intjn * 

jsr wincLcal * 

tst.w int_ou tt 

beq appLexi * 

* 

* Calc new window bordered area 

# 

move.w #1, int_in * 

jsr wind_cal * 

tst.w inuou * 

beq appl^exi # 


~4 

0 
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Digital Research 

Alloc space for full size window 


* Hi soft GST Metacmm Seka 


wind_cre : 





move.w 

#1 00 , control 




move . w 

.control +2 




move.w 

#31 h control+4 



# 

move . w 

#$0, control +6 




move.w 

#$0f f f . intjn 

# 

edges 


move.w 

i nt_ou+2 p int_jn + 2 

* 

xl 


move . w 

i nt_ou+4 . int_in+4 

* 

yi 


move.w 

int_ou + G,int_in*6 

* 

x2 


move.w 

int_ou+8. int_in+8 

# 

y2 

# 

jsr 

aes 




move.w 

i ntj^u , whandl 




tst.w 

i nt_ou 



* 

beq 

appl_exi 



s 

i 

Open window at last # 



wind_ope : 





move.w 

#101 p control 




move.w 

#$5 i control+2 




move.w 

#31 .control *4 




move.w 

#30. control *6 




Absolute parameters 


move.w 

move.w 

move.w 

move.w 

move.w 

jst 

move 

tst .w 

beq 


whandl f int_in 
#0 , i ntJ n+2 
#0,inUin+4 
#280 . i nt_i n+6 
#160,1 nt_i n+8 
aes 

int_ou 

appl_exi 


xl 

yi 

x2 

y2 


Do something on the screen, this is where your program starts. 


L - IS 


r 


m 




ST- 

i 

a 

IM 

H * 

■ 



■ 


mv 

■ 

f 

■ 


i: 

. 

s; ; 

i 

3 

i 

■ 

e« > 



c: ! 

i 



j? 

::i 

i 


— m 

,! 

i 


F ! 

i 


E ! 

i 

C 



i 

: 

c 

— M 

r* 

1 

t 

5“ 


i j 

m* ' 

i 

! 3 

mn 

i 


i 


1 n 


i 

! 

mr 


! ^ 
3 





■ 

3 


# Digital 

Research 

4 Hi soft 

* Set screen parameters * 

# 


vsf Jnte: 

move . w 

#23. contr 1 

# 

move.w 

#0,contrl+2 

* 

move w 

#1 .contrl+6 

# 

move .w 

whandl , contr] +1 2 


move.w 

#1 1 intin 4 solid 

# 

jsr 

vdi 

* 

* Style 

* 

t 


vsf_sty1 : 

move.w 

#24. contrl 

* 

move.w 

#0 1 contrl+2 

* 

move.w 

#1 .contrH6 

# 

move.w 

« 

whandl ,contrl+12 

* 

move.w 

#1 1 intin 4 n.a 

* 

Jsr 

> 

vdi 

* 

4 Colour 

* 

* 


vsf.colo: 

move.w 

#25. contrl 

* 

move.w 

#0 pContrl+2 

* 

move.w 

#1 .contrl + 6 

* 

move.w 

* 

whandl .contrl+12 

* 

move.w 

#1 .intin 4 black 

* 

jsr 

* 

vdi 

* 

* Set mouse style 4 

» 


grafjrou; 

move.w 

#78. control 


move.w 

#31 .control +2 


move.w 

#31 , control+4 

■ 

move.w 

t 

#31 , control+6 


move.w 

#30, i nt_i n 


jsr 

aes 

# 

tst.w 

int_ou 


beq 

# 

appLexi 

i 



* 
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1 Digital Research 
* Get position of window work area 


Hi soft GST Metacomco Seka 


where: 

move.w whandl , int_in 
move . w #4 , intJn+2 
jsr wind_get 

tst.w int_ou 
beq appLexi 


* work area 


* Get coordinates within work area 

# 

addrw #35,int^ou + 2 
add.w #35,int„ou+4 
sub w #50,int„ou+6 
sub.w #50. int_ou*8 

* 

* Draw a shape from those coords 

# 

v^rfbox: 

move.w #1 1 .contrl 
mova.w #2, contrl* 2 
move .w #0, contrl + 6 
move.w #9, contrl + 10 
move.w whandl .contrl + 1 2 


Absolute coords - not window the reason for this patch 


move .w 

int_ou+2 .ptsin 


move .w 

i nt_ou *4 . ptsi n*2 


move.w 

int_ou + 6 , ptsin+4 


move.w 

int-Ou + 8,ptsin+6 


jsr 

* 

vdi 


* Wait for a sign - about 1 

* 

mi 

evntjtim: 



move .w 

#24 .control 


move.w 

#$ 2, control +2 


move.w 

#$1 .control+4 


move .w 

#SG .control +6 


move.w 

#$f fff , tnt_in 

tt Lo 

move.w 

#$0000. int_in+2 


jsr 

aes 


• End of 

program, shut the 

i wil 


Digital Research * Hi soft GST Metacomco Seka 

Close v„scrn Stop o/p (Shut window down) * 


v_clsvwk: 



move.w 

#101 .contrl 

# 


move . w 

#0.contrl+2 

* 


move rw 

#0 s eontrl+6 


# 

move.w 

vhandl . contrl +1 2 

# 

ft 

ft 

Close window 


wind_clo: 




move.w 

#1 02 , control 

# 


move.w 

#$1 , controls 

# 


move.w 

#$1 , control +4 

t 

# 

move.w 

#$0, control +6 

* 


move . w 

whandl , intjn 

# 


jsr 

aes 



tst.w 

i nt_ou 

* 

# 

beq 

appLexi 


# 

* 

Deallocate space and handle * 


wind_del : 




move.w 

#103 .control 

# 


move.w 

#$1 r control+2 

ft 


move , w 

#$1 ..control +4 


# 

move.w 

#$0 , control +6 



move.w 

whandl , int_in 



jsr 

aes 



tst.w 

int_ou 

* 

* 

t 

beq 

appLexi 

* 

* 

* 

Call APPL_EXr (Last call) * 


appLexi : 




move.w 

#19 P control 

* 


move.w 

#$0, control +2 

* 


move rw 

#$1 .control *4 

# 


move.w 

#S0, control + 6 



jsr 

aes 

# 


move.w 

int_ou f d0 

# 


rts 




Subroutines 
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* Digital Research 


* Hi so ft GST Metacomo Seka 


* Get window data 

* 


wind.get : 

move .w 

#104 .control 

* 

move .w 

#$2 f control+2 

* 

move . w 

#$5 . control +4 

# 

move .w 

#S0, control+6 

* 

* move.w 

vhandl.intjn 

rem * 

4 move.w 

#7 , int_in + 2 

out 4 

jsr 

aes 


rts 



4 Calculate window work area ! 

based on facilities: title. 

4 scroll 
* 

bar etc. 


wincLcal ; 

move .w 

#1 08 .control 

* 

move , w 

#$6. control+2 

* 

move .w 

#$5,contro1+4 

i 

move .w 

#$0, control +6 

# 

4 move.w 

#0,int_in 

rem out 4 

move.w 

#$0fff ,int_in + 2 * 

edges * 

move .w 

int_ou + 2 t int_in+4 4 

xl * 

move .w 

int_ou+4,intJn+6 4 

yl 

move.w 

int_ou+6 , i ntj n+8 4 

x2 

move .w 

int_ou+8 p intjn + 10 

4 y2 

jsr 

aes 

1 

rts 


# 

* 

1 VDI parameter block call 

# 


vdi : 

move . 1 

#contrl , pblock 1 

1 reset * 

move . 1 

#pblock,d1 

# 

move . 1 

#1 1 5 , dO 

# 

trap 

#S2 

# 

rts 

* 



4 AES parameter block call 

« 


aes: 

move . 1 

^control ,_c 

4 reset 4 zc 

move . 1 

#_c,d1 

* . #zc 

move. 1 

#200, dO 

* 

trap 

#52 

# 

rts 




* 
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* Digital Research * //iso ft GST Metacomo Seka 

4 Set up AES array 

« 

ini_aes: 


move*! 

#control 

* 


. IQ 


. zc 

move* 1 

#global ,_c+4 

* 


. zc+4 


. zc+4 

move. 1 

#int_in,_c+8 

* 


. zc+8 


. zc+8 

move . 1 

#int_ou,_c+T2 

# 


. zc+12 


. zc+12 

move , 1 

#addr_in H _c+1 6 

» 


. zc+16 


, zc+16 

move . 1 

#addr_ou,_c+20 

# 


. zc+20 


* zc+20 

rts 

# 


# 





4 Set up 
* 

VDI array 






ini_vdi : 







move „ 1 

#contrl t pblock 

* 





move . 1 

#intin,pb]ocfc*4 

* 





move . 1 

#ptsin,pblock+8 

* 





move . 1 

#intout,pblock+12 

t 





move . 1 

#ptsout,pblock+16 

* 





rts 


# 





4 Make 

space for the arrays. You 

must 

ensure 

these 

are 

large 

4 enough to hold the array's data. 

Be especially careful 

regarding 

4 the spelling of the array names. 

# 






bss 


# 

XXX 

section 

d 

. data 

even 


* 

xxx 

xxx 


xxx . xxx 


ds.l 256 

* 




. blk.l 

ustk : 

# 

ds.l 1 

* 




. blk.l 

pblock: 

ds.l 5 

* 




, blk.l 

contrl : 

ds.w 12 

* 




. blk.w 

intin: 

ds.w 30 

* 




. blk.w 

ptsin: 

ds.w 30 

# 




. blk.w 

intout: 

ds.w 45 

* 




. blk.w 

ptsout: 

* 

ds.w 12 

* 




. blk.w 

handle: 

ds .w 1 

* 




. blk.w 

vhandl : 

ds .w 1 

* 




. blk.w 

whandl : 

ds.w 1 

* 




. blk.w 
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* Digital Research 


* Hisoft GST Metacomco Seka 


_c; 

ds.l 

6 

control : 

ds .w 

5 

global : 

ds, w 

ie 

intJn: 

ds,w 

16 

int_ou: 

ds.w 

7 

addr_in: 

ds.l 

2 

addr^ou ; 

ds. l 

1 


end 


* , zc .zc blk.l 

* . . blk.w . 

* .blk.w . 

* . .blk.w . 

* . . .blk.w . 

* . . blk.l . 

* L . blk.l . 


The program may be assembled and linked (if required) using the assembler calling 
procedures outlined in Appendix K. 
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TOS 


DISPLAY DEMONSTRATION PROGRAM 

The following program shows a typical Atari TOS file, which simply inverts the 
current mono display color for those programmers who,like myself, prefer white on 
black or toggles the border of a color display. 


Digital Research 


Hi soft GST 


Meta . Seka 


Demo Atari TOS program 


text 


xxx section c 


code 


move. 1 
move. 1 
move . 1 
move. 1 
add J 
add . 1 
add . 1 
move . 1 
move . 1 
move 
move 
trap 
add. 1 
jsr 

move . 1 
trap 


a7,a6 
#u s t k , a 7 
4(a5) , a5 
Sc(a5) ,d0 
S14(a5) r d0 
$1c(a5),dG 
#$100, dO 
dO,-(sp) 
a5 . - ( sp) 
dO.-(sp) 
#$4a , - (sp) 
#1 

#$c,sp 
start 
#$0, -{sp) 
ffl 


set 


37 


free unused 
back to GEM 

jump to prg 
terminate 


start: 
clr.1 
move.w 
trap 
move. 1 
move . w 
jsr 
eon 
jsr 
exit: 
move. 1 
move . w 
trap #1 
move . 1 
trap 


"(sp) 

#32.-(sp) 

#1 

d0 F a1 
JM.dO 
newcol 
#1 ,d0 
newcol 

al -"(sp) 

#32 , - (sp) 


#1 


r{Bl) 


set super 


get/set col 


set user 
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* Digital Research 
neweol : 

move.w dO , - ( sp) * get color 

move.w #0,-(sp) 

move.w #7,-(sp) 

trap #14 

add.w #6.sp 

rts 

* 

bss 

ds.l 20 
ustk: ds.l 1 


* Hisoft GST . Mela . 



* xxx section d 


end 


The above program is assembled and linked without any other files. 


Seka 


data 

blk,l 

blU 
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TOS HEADER FILE 

The following shows a typical Atari TOS header file that may be incorporated in a 
user- written program to provide access to the base page offset variables. 


ft f 4 4 ft 4 # *ft#ft*444**4***#*ftft#*4#ftftft#ft 

Base page format initialised by BDOS 



Itpa 

equ 0 

• Low TPA address 

htpa 

equ 4 

* High TPA address + 1 

IcoiJe 

equ 8 

* Text segment start 

codel en 

equ 12 

# Length of text segment 

Idata 

equ 16 

* Initialized data segment start 

datalen 

equ 20 

4 Length of initialized data 

Ibss 

equ 24 

tt BSS segment start 

bsslen 

equ 28 

# Length of uninitialized data 


either GEMDOS 

4 dta 

equ 32 

* pointer to DTA address 

•parent 

equ 36 

* pointer to parents base page 


ecu 40 

* reserved 

*env 

equ 44 

* Environment string pntr (GEMDOS) 

«■ 

•' 

or Atari 

OS 

freelen 

equ 32 

• Free memory length after BSS 

ldriv 

equ 36 

* Drive from which program loaded 

resvd 

equ 37 

* Reserved 

f cb2 

equ 56 

4 2nd parsed fcb 

fcbl 

equ 92 

4 1st parsed fcb 


common tail 


command equ 128 * Command tail 


Although it is good practice to size the memory requirements of your program and 
return the unused memory to GEMDGS, programs can be written without if they 
return to the GEM desktop. 


GEM allocates all the memory to the program, only if it multi tasks or calls and loads 
another program is there any real need to return spare memory. 
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CHARACTER PRINTING PROGRAM 

This simple program demonstrates some of the methods available for priming to the 
VT 52 screen. The compiled program may be installed as: 


A "GEM program' - the busy bee cursor will appear in the display and leave a hole 
when moved* 

A "TOS program' - with flashing cursor, the cursor may be hidden quite easily by 
incorporating within the prdat string the "hide cursor' escape code as specified in 
Appendix C 

* Digital Research * Hi soft GST Metacomco Seka 

* 

* Monochrome TQS VT52 screen print program (0,0 to 24,79) 


(For colour, set max print width in 

text 



* 


gem BIOS 

type print 


dr. 1 

d4 

* Clear d4 

4 

clr.l 

d5 

* Clear d5 

# 

lea 

prdat, a4 

* Get data address 

« 

move . b 

{a4} P d4 

* Data count-1 

* 

oop; 




adda.l 

#1 -a4 

* Get next 

# 

move . b 

{a4),d5 

4 Get char byte 

* 

move.w 

d5,-(sp) 

* Stack char.w 

f 

move.w 

#2 T -(sp> 

# Send to console 

# 

move.w 

#3 r - ( sp) 

4 Set bconout ( ) 

* 

trap 

#13 

# Call it 

* 

add.w 

#6.sp 

4 Tidy stack 

* 

dbra 

d4 , cloop 

* loop for next 

1 


GEM BD0S 

type print 


lea 

mess , aO 

# GetASCl I string 

* 

move,! 

a0,-(sp) 

4 Stack it 

fr 

move . w 

#9, -Up) 

* set conws() 

tt 

trap 

#1 

4 Call it 

* 

add .w 

#6,sp 

4 Tidy stack 

* 


xxx section c 


code 


move . 1 #200 , dl 
exlp: 

moved #-1,d0 
dloop: 
dbra 
dbra 


dG, dloop 
dl ,exlp 


Wait 
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Digital 

Research 


* Hi soft GST 

Metdcomo 

Seka 

move.1 

#0.-U7) 

4 GEM return 

* 



trap 

#1 

# 

* 



rts 


# Return 

* 



data 



4 xxx section 

dl 

xxx 

even 



* xxx xxx 

xxx * 

xxx 


VT52 screen location character equivalents 


» m » 

"Ll » 

If ■ 3 

prut ■ mm 
m if h h 

I 

E | 3 

El- 2 3 
6: 1 3 
E § 3 

J V- I - 4 

:: 2 3 

r - 3 

ZiZ 

til 

T 

E r i 


* ! " # $ % & ' ( ) * + P - . / 0 1 2 3 4 5 6 

1 0,1 ,2,3.4,5,6,7,8,9.10,11 ,12 ,13,14,15,16 ,17,10,19,20,21 ,22 

* 

*78 9 : ;<->?@ABCDEFGHIJ 

*23,24,25,26,27,28,29,30,31 ,32 ,33,34,35, 36,37 .38,39,40,41 ,42 

f 

*KL«N0PQRSTOVWXYZ [\] 

4 43, 44 , 45,46,47,48 ,49,50,51 ,52,53,54,55.56,57,58,590.60,61 

# 

*a_' abode fghijklm no 

* 62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79 

* 

* Data string to print {See Appendix C for codes) 


section d2 


prdat :dc.b 

50 

Length of text -1 

dc.b 

27, ‘E f 

Clear screen 

dc.b 

27, , b t ,0 

foregnd col white 

dc.b 

27, 'cM 

backgnd col black 

dc.b 

27, ( Y 0,0‘ # 

Set cursor at 0,0 

dc.b 

27 . 1 Y ! ! 1 , 1 1 * 

Set cursor at 1 ,1 

dc.b 

27,‘bM 

foregnd col black 

dc.b 

27 . T c 1 ,0 

backgod col white 

dc.b 

27 r 1 Y8f 24 . 69 ' 

4 Set curs % 24,69 

dc.b 

27 * f p 1 

Inverse video 

dc.b 

27, -I 1 

Up 1 line 

dc.b 

■hi ! 1 

Say something witty 

dc.b 

27, 'Y, 4' 

set cursor at 12,20 

dc.b 

27, 'q 1 

Reset video 


even 
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* Digital Research 

• //i soft GST Metacomco Seka 


M „t null terminated string ■ gs.s ASCII & control cote 


* 

* . even 

* 

i . 

f 

mess: dc.b ’hello 1 
dc.b 10.10,7 
dc.b 'hello* 
dc.b 10 
dc.b 'hello 1 
dc.b 10.13 
dc.b 'hello’ 
dc.b 0 

t 

* Alternative print 

* method for screen 

* printing. 

* Text 

* linefeed 

* carriage return 

* and a bell 

* E" d of string , . even 

* 

* 

end 
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SOUND DEMONSTRATION PROGRAM 

This program provides a basic introduction to 4 sound' programming on the Atari 
ST; where experimentation with each of the sounds provided is perhaps the best 
approach to understanding the effects of each argument. 

Take care of the following general points: 


User stack Make sure it is large enough. It grows down in memory and it can 
overwrite the data area. 

Tinting It is necessary to provide a delay before an exit back to GEMDOS, TOS 
could reallocate the sound data bytes space. 


* Digital Research 


* Hi soft GST Metacomco Seka 


* Experimental TOS sounds program 

* 

text 

* 

move.] 37,35 * create 

move.l #ustk,a7 # space for 

move . 1 4(a5) , a5 * program 

move.l Sc (a5) . dO 

add . 1 $14(05) .dO 

add. 1 $1c(a5) ,d0 

add. 1 #$100, dO 

move.l d0,-($p} 

move.! a5.“(sp) 

move d0,-(sp) 

move #$4a,-(sp) 

trap #1 

add . 1 #$c,sp 

c 

start: 

move.l tfsoundl ,a1 * 

jsr dosound # 


move.] #1 SO.cll # 15 secs 

loopo : 

moveq #-1 t d2 # wait for 

loopi : 

dbra d2 P loopi # finish 

dbra dl ( loopo 


xxx section c 


exit: 

cl r 1 -(sp) # GEMDOS ret 

trap #$t * 

rts 


code 
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* Digital Research 
dosound : 

move.! al.-(sp) 
move.w #32, “( S P) 
trap #14 
add.w #6,sp 
rts 

bss 

even 


* Hi soft GST Metacomco 


ds.l 
jstk: ds.l 

§ 

data 

even 

* 

soundl ; 


64 

1 


sound pointer 4 


Large enough not 
to overwrite data * 


Bell 


xxx section dl 
XXX . xxx + xxx 


xxx section d2 
xxx . xxx * xxx 


dc.b 

0,534 

*\ chan A 

dc.b 

1.0 

V 2150 hz 

dc.b 

2,0 

* \ chan 

dc . b 

3,0 

* / B 

dc.b 

4,0 

*\ chan 

dc.b 

5,0 

V c 

dc.b 

6,0 

* noise 

dc.b 

7 . Sf e 

* enable ^ 

dc.b 

8, $10 

* enable / 

dc . b 

9,0 

* B off 

dc.b 

10,0 

* C off 

dc.b 

11,0 

*\S ingle i 

dc.b 

12. $10 

#4 envelop 

dc.b 

13,9 

V 10 0 

dc.b 

130,100 

# delay 


Seka 


data 

xxx 

blik . 1 

blk.l 

code 

xxx 
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s 

3 

: 

a 

a 

3 

3 

3 

i 

I 

1 

3 

3 

3 

H 


Digital Research 


sound 2: 


* Hi soft GST Metacomo Seka 


Si ren 


sound 


sounds 


sound 


dc.b 

0,$fe *\ chan A 

# 

dc.b 

1 ( 0 V 440 hz 

Hi note* 

dc.b 

2,0 * \ chan 

* 

dc.b 

3,0 * / e 

* 

dc.b 

4,0 *\ chan 

* 

dc.b 

5.0 7 c 

* 

dc.b 

6.0 * noise 

* 

dc.b 

7, $fe * enable A only * 

dc.b 

8,11 * A amplitude * 

dc.b 

9,0 * B off 

# 

dc.b 

10,0 * C off 

* 

dc.b 

11,0 *\ no 

* 

dc.b 

12.0 * envelope 

* 

dc.b 

13,0 7 shape 

# 

dc.b 

130,20 * 

# 

dc.b 

0, $56 # \ chan A 

Lo note* 

dc.b 

1,1 7 187 hz 

# 

dc.b 

1 30 r 20 * 

* 

dc . b 

0. 9fe , 1 , 0. 1 30. 20 

*Hinote* 

dc.b 

0.956. 1,1. 130. 20 

*Lonote* 


* 

silence 

dc.b 

8,0, 9,0 ■ A a 6 off * 

dc.b 

130,50 * 

* 

3: 

* 

gunshot 

dc.b 

0,0,1. 0,2. 0,3.0, 

4, 0,5,0 * 

dc.b 

6.15 * medium noise period 

dc.b 

7,199 # enable noise chans 

dc.b 

8,16 * \ using 

# 

dc.b 

9,16 4 envelope 

dc.b 

10,16 * / control * 

dc.b 

11,0 *\ envelope period* 

dc , b 

12,16 7 

* 

dc.b 

13,0 * one cycle decay # 

dc.b 

130,25 * 

# 

[ 

# 

silence 

dc . b 

8. 0,9.0 * A & B 

off ■ * 

dc . b 

130,50 * 

* 


,B & C 
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Digital Research 


Hi so ft GST Hetacomo Seka 


sound4 : 


explosion 


dc.b 

0 . 0 . 1 , 0 . 2 , 0 . 3 , 0 , 4 , 0 , 5,0 * 

dc.b 

6,10 

# noise period * 

dc.b 

7.199 

* enable noise chans / 

dc.b 

8,16 

* \ using 

dc.b 

9,16 

# envelope 

dc.b 

10,16 

# / control * 

dc.b 

11 ,0 

*\ envelope period* 

dc . b 

12,80 

V 

dc.b 

13,0 

4 one cycle decay * 

dc.b 

130.120 

* * 


A h B h 


sound 


si 1 ence 


dc.b 8.0,9.0,10,0 * A Bi C off 
dc.b 130.100 * 


* sounds : 


whistle 


dc.b 0 , 0 . 1 ,0.2, 0,3,0. 4, 0,5, 0.6,0 

dc.b 7,254 * enable tone A only 

dc.b 8,15 * 

dc.b 9,0,10.0,11,0.12,0,13.0 * 
dc.b 128,60 * Initial tempreg * 
dc.b 129,0,-2.40 * reg-step-end* 
dc.b 130,2 * 

# 

1 exit list 

* 

dc.b 7,255,8,0 * off 
dc.b 265,0 * return 


end 


even 
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A-Line 


A-LINE PARAMETER TABLE 

The following is the complete list of the A-line equates and functions. It may be 
used as a standard assembler header file to A-line programs. 


11 A-line parameter table 

#!*##*«*»*«******** «** * t ***#t#4t4*f##**t4**##«# 


VJ)ELHT 

equ 

-46 

* .W Pixel cell height 

V,CELJIX 

equ 

“44 

* .W Maximum cells across -1 

V_CEL_MY 

equ 

-42 

* . W Maximum cells high -1 

V.CELWR 

equ 

-40 

* .W Offset to next cell 

V_C0LBG 

equ 

-33 

# W Background index color 

V_C0LFG 

equ 

-36 

* . W Foreground index color 

V_C0R_AD 

equ 

-34 

* ,L Current cursor address 

V.CUOFF 

equ 

-30 

* M Offset to 1st cell 

v_curj;x 

equ 

-28 

* .W X cursor position 

V_CUFLCY 

equ 

-26 

* ,W V cursor position 

V_CUR_CNT 

equ 

“24 

* B Cursor flash interval 

V_CUR_TIM 

equ 

-23 

4 . B Cursor countdown timer 

V_ FNT_AD 

equ 

-22 

* . L Font address 

V_FNT_ND 

equ 

-18 

* .W Last font ASCII code 

V_FNT_ST 

equ 

-16 

# .W 1st font ASCII code 

tf£?NT_WR 

equ 

-14 

# ,W Font width 

V_X_MAX 

equ 

-12 

* W Maximum X pixel screen value 

V_0FF_AD 

equ 

-10 

* -L Font offset table address 

OTATUS 

equ 

-6 

* .W Text status byte 

V_y_MAX 

4 

equ 

-4 

* ,W Maximum Y pixel screen value 

VPLANES 

equ 

0 

* M # video planes 

VWRAP 

equ 

2 

* .W # bytes/video 

CONTRL 

equ 

4 

* L \ 

INTIN 

equ 

8 

* . L 

PTSIN 

equ 

12 

* . L array pointers 

INT0UT 

equ 

16 

* , L 

PTSOUT 

equ 

20 

# L / 

CDLBITO 

equ 

24 

* .W \ 1 * ) 

C0L6 1 71 

equ 

26 

4 w * 2 * ) write 

C0LBIT2 

equ 

28 

* W * 4 # ) color 

C0LBIT3 

equ 

30 

* .W / 3 * ) 

LSTLIN 

equ 

32 

# ,W -1 
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LNMASK 

WMODE 

ft 

XI 

Y1 

X2 

X2 

* 

PATPTR 

PATMSK 

HFILL 

CUP 

* 

XMINCL 

VMIWCL 

XMAXCL 

YMAXCL 

XDDA 

DDA1NC 

SCALD I R 

ft 

MONO 

SRCX 

SRCY 

DE5TX 

DESTY 

DELX 

DELY 


equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 

equ 


34 * .W VD1 line style 

36 * W Write mode 

38 1 M \ 

40 * M coordinates 

42 ' M 

44 * . W / 

46 # .1 Current fill pattern pointer 

50 # .W Length of fill pattern mast 

52 * -W O^single plane 

54 * .W 0_no clipping 


56 1 
58 
60 
62 
64 
66 
68 

70 

72 

74 

76 

78 

80 

82 


FBASE 

equ 

84 tt 

fvjidth 

equ 

88 # 

STYLE 

equ 

90 # 

litemsk 

equ 

92 * 

SKEWMSK 

equ 

94 * 

WEIGHT 

equ 

96 * 

FtOFF 

equ 

98 * 

loff 

equ 

100 1 

SCALE 

equ 

102 1 

CHUP 

equ 

104 ! 

TEXTFG 

equ 

106 

SCRTCHP 

equ 

108 

SCRPT2 

equ 

112 

TEXTBG 

equ 

114 

COPYTRAN 

equ 

116 

SEEDABORT 

equ 

118 


W \ 

,W Clipping 
W values 

■W / 

W txtblt x dda accumulator 
M txtblt scale factor 
.W G_down 

.W 0_font monospaced 
_y \ Coordinates of character 
/ in font form 

y \ Coordinates of character 
.W / on screen 

* .W Charachter width 

* W Charachter height 

. L Font form pointer 
W width 
,W style 
W Lighter text mask 
M Skew text mask 
.W Extra text width 
M High offset skew 
VJ Low offset skew 
.W Ojio scaling 

O_hori zontal orientation 
M Text foreground color 
P L Text effects buffer 
W Offset to scale buffer 
W Text background color 
f W Copy raster type flag 
* W Abort fill routine pointer 


it 
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A-line function calls 




ft 


init 

equ 

$a000 



putpi x 

equ 

i nit+1 

* 

Put pixel 

getpix 

equ 

i nit+2 

• 

Get pixel 

abl ine 

equ 

i nit+3 

# 

Draw a line 

habl ine 

equ 

init+4 

* 

Horizontal line 

rectf i 1 1 

equ 

i n i t * 5 

* 

Draw filled rectangle 

polyfill 

equ 

i nit+6 


Draw 1 line polygon fill 

bi tbl t 

equ 

i nit+7 

* 

Bit block transfer 

textbl t 

equ 

i nit + 8 

4 

Text block transfer 

showcur 

equ 

i nit+9 

ft 

Show mouse 

hidecur 

equ 

i ni t+10 

ft 

Hide mouse 

chgcur 

equ 

Vnit+il 

f 

Transform mouse form 

unsprite 

equ 

init+12 

ft 

Undraw previous sprit 

drsprite 

equ 

i nit+1 3 

ft 

Draw sprite 

copyrstr 

equ 

init+14 

ft 

Copy raster form 

seedfi 1 1 

equ 

init+15 

ft 

Polygon fill 



'[ 
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SPRITE DEMONSTRATION 


The following A-line program is deliberately compressed to show the small number 
of lines of assembler used to control sprites. The program produces an alternate 
black and white sprite crossing a monochrome screen. 


• Digital Research 

* Hi soft 

GST Metacomco Seka 


ini t 

equ iaOOO * initialize 

init: 


unsprite 

equ init+12 * undraw sprite 

unsprite: 


drsprite 

equ init+13 * draw sprite 

drsprite: 


VJUMAX 

equ -1 2 

* Max X pixel scrn val . VJLMAX: 


t 

text 


* xxx 

section c . code . 


start: cl r 

1 * (Sp) 

4 Set * 


*1 

move .w 

#520 , -(sp) 

4 super 


4 1 

trap 

#1 

# mode 


*1 

addq . 1 

#6.sp 



4 1 

move . 1 

dO , stksv 

tt save stack* 


*1 

move.w 

#Q,olda 

* versn flag* 


*2 

move . 1 

#0.a2 

# *■ 


4 2 

dc.w 

init 

* Init * 



trove. 1 

a2 ,d2 

1 aline * 


*2 

bne 

a2ok 

4 registers * 


*2 

lea 

#-60(a1).a2 

4 4 <-- - 

- -60(a1);,a2 > . 

*2 

move .w 

#-1 ,olda 

* * 


4 2 

a2ok: move . 1 S34(a2) , a3 

4 draw addr (4*13) 


*2 

move .w 

#VJLMAX(a0),a5 

4 get max width <--- 

- V_XJ1AX(a0) ,ah — . 


move.w 

#0 , dO 

4 init x * 



move .w 

#50 , dl 

4 init y * 



move.w 

#10.62 

* scan count* 



lea 

sprit, aO 

4 sprite add* 



lea 

save ,a2 

4 bg savearea 



movea . 1 

1 a0,a4 

4 sprite col* 

* 


adda . 1 

#6.a4 

4 pointer * 

♦ 


setcol : move.w (a4) ,d3 

4 get color * 



bne 

white 

* * 



move . 1 

#S00010001.(a4) 

4 black 



bra 

loop 

4 color * 



white: move . 1 #0, (a4) 

* set white 1 



loop: movem.l dO-dS/aO-aS, - (sp) *sav r 4 



tst w 

olda 

4 test versn 4 


4 2 

beq 

new 

tt * 


4 2 

jsr 

(#3) 

4 old versn 4 


*2 

bra 

cont 

» * 


*2 


IL 


= S 
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Digital Research 


Hi soft GST Metacomco Seka 


i ms 


new: dc.w 

cont: move.w 

wait: dbra 


drsprite 
#2000 .dO 
dO f wai t 


lea 
dc ,w 
movem „ 1 
add.w 
cmp.w 
ble 

move .w 
add.w 

sub.w 
bne 
move . 1 
move .w 
trap 
addq . 1 
move . w 
trap 

data 

even 


save fc a2 * 

unsprite * 

(sp) + f d0-d3/a0-a3 
#1 t d0 

a5,d0 * 

loop * 

flO.dO 

#10. dl 

#M2 
setcol 
stksv t - (sp) 

#520, -(sp) 

#1 

#6,sp 
#0, sp) 

#1 


sprit: 


ghoul 


dc.w 

dc .w 
dc.w 
dc.w 
dc .w 
dc.w 
dc . w 
dc.w 
dc.w 
dc.w 
dc.w 
dc .w 
dc.w 
dc.w 


0,0 

-1 

0 

0 

Sffff 

$03c0 

Sffff 

mm 

Sffff 

Slff8 

Sffff 

$3ffc 

Sffff 

S73ce 


new versn * 
* 

delay 4 
bg savarea* 

t 

tt unsave r* 
slide over 4 
screen # 

init x * 
drop y # 

count down* 
and again * 
back * 

to 

user * 
mode * 
back * 
to GEM 4 


XXX 

xxx 


section d 
xxx 


x,y 4 

tt 1_vdi. -1_xor 

# bg col # 

* fg col tt 


■ ™ ■ 

* I 


dc.w 

S73ce 

tt 



dc .w 

Sffff 

tt 

- B 

vm i 


dc.w 

$ffff 

tt 

| 

dc .w 

Sffff 

tt 



dc.w 

Sffff 

tt 

1 


dc.w 

Sffff 

tt 

mi i 

5 

dc.w 

$fbdf 

t 



dc.w 

Sffff 

* 

— i 

KILL: l 

mi l | 

3 

dc .w 

Sf81f 

t 


xxx 


xxx 

xxx 


*3 

*3 


M 

4 1 

*1 

*1 
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Digital Research 

dc.w 

Sffff 

dc .w 

Sffff 

dc.w 

sffff 

de.w 

$67e6 

dc .w 

Sffff 

dc.w 

$300c 

dc.w 

$ffff 

dc >w 

$1 ffS 

dc.w 

Sffff 

dc.w 

$0420 

dc .w 

Sffff 

dc.w 

# 

$1818 

bss 


even 


+ 


stksv; ds . 1 

1 

save: ds b 

74 

olda: ds.w 

1 


* 


end 


* Hi soft GST Metacomco Seka 



* xxx section d 

* xxx . XXX . XXX 


data - 

XXX , 


. blk.l . *1 

. blk b . 

. blk.w . *2 


*1 There is no requirement to run this program in supervisor mode, these line, 
code may be ommittcd. 

*2 Some versions of the disk based TOS incorrectly return the value of A2. These 
lines of code are not requred by ROM based versions of the ST. 

*3 The use of the following code provides more stable sprites + 

MOVE #37 , - (sp) * wait for Vblank 

TRAP #14 4 XBIOS cal 1 

ADDQ #2 , sp * tic, y stack 

The programmer might also contemplate hiding the busy-bee cursor. 
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ADE 

AES 

A CIA 

ANSI 

ASCII 

AUX 

BCD 

BDOS 

BIOS 

BPB 

BSS 

CCP 

CCR 

CON 

CP/M 

CPU 

CRC 

CTS 

DCD 

DIR 

DMA 

DOS 

DPB 

DS 

DTR 

D/A 

EPB 

FAT 

FCB 

FDC 

FIFO 

GDOS 

GEM 

GIOS 

GP 

Grd 

GSX 

HDC 

ID 

ikbd 

IPL 

I/O 


ASCII decimal equivalent 

Application environment services 

Asynchronous communications Interface adaptor 

American national standards institute 

American standard code for information interchange 

Auxilary 

Binary coded decimal 
Basic disk operating system 
Basic input/output system 
BIOS parameter block 
Block storage segment 

Console command processor 
Condition code register 
Console 

Control program for microcomputers 
Central processing unit 
Cyclic redundancy check 
Clear to send 

Data carrier detect 
Directory 

Direct memory access 
Disk operating system 
Disk parameter block 
Double sided 
Data terminal ready 
Digital to analogue 

Exception parameter block 

File allocation table 
File control block 
Floppy disk controller 
First in first out register 

Graphics device operating system 
Graphics environment manager 
Graphics input/output system 
General purpose 
Ground 

Graphic system extension 


ft = 3 
!■ j 3 
ft £ £ 


I 




W 


1 

i: 

1 

i! 


Ts 


iw 


I 

f 
i 
i 
i 
i! 
I 

m\ w 

:n 


S = 3 
3 


3=3 

b 

3 

3 


in 


Hard disk controller 

Identification 
Intelligent keyboard 
Interrupt level 
Input/output 


miw u 

' 1 




u 
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1 


LPB 

LSB 

LST 

Load parameter block 
Least significant byte/ bit 
List 

MD 

MFDB 

MFP 

MIDI 

MS-DOS 

MSB 

Memory descriptor 
Memory form definition block 
Multi function peripheral 
Musical instruments digital interface 
Microsoft disk operating system 
Most significant bit 

NDC 

Normalized device coordinates 

OEM 

OS 

osc 

Other equipment manufacturer 
Operating System 
Oscillator 

PC 

PC-DOS 

pk-pk 

PSG 

Program counter 

IBM personal computer operating system 
Peak to peak 

Programmable sound generator 

RAM 

RC 

RF 

RGB 

Ri 

ROM 

RSX 

RTE 

RTS 

Rx 

Random access memory 
Raster coordinate 
Radio frequency 
Re d-green-blu e 
Ring 

Read only memory 
Resident system extension 
Return from exception 
Return form subroutine 
Receive 

SASI 

SCSI 

SP 

SR 

SS 

SSP 

Shugart associates standard interface 
Small computer systems interface 
Stack pointer 
Status register 
Single sided 

Supervisor stack pointer 

TOS 

TPA 

TTL 

Tx 

The operating system 
T ransient program area 
Transistor- transistor logic 
Transmit 

ULA 

USART 

Uncommitted logic array 

Universal synchronous /a synchronous receiver/ transmitter 

USP 

User stack pointer 
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VBI 

VDI 

VLSI 


Vertical blank interrupt 
Virtual device interface 
Very large scale integration 


Appendix N 
Schematic diagrams 
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ATARI ST peripheral control diagram 
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ATARI ST schematic diagram 
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